Task_Reporter/openspec/changes/archive/2025-12-04-add-open-room-access/specs/chat-room/spec.md

chat-room Specification Delta

MODIFIED Requirements

Requirement: List and Filter Incident Rooms

The system SHALL provide endpoints to list incident rooms with filtering capabilities. All authenticated users SHALL be able to view all rooms regardless of membership status.

Scenario: List all rooms for authenticated user (MODIFIED)

• WHEN an authenticated user sends GET /api/rooms
• THEN the system SHALL return ALL rooms in the system
• AND include room metadata (title, type, severity, member count, last activity)
• AND include is_member flag indicating if user is a member
• AND include current_user_role (null if not a member)
• AND sort by last_activity_at descending (most recent first)

Scenario: Filter rooms with membership filter

• WHEN a user sends GET /api/rooms?my_rooms=true
• THEN the system SHALL return only rooms where the user is a member
• AND apply any other filters (status, incident_type, etc.)

Requirement: Room Self-Join

The system SHALL allow any authenticated user to join a room as a VIEWER without requiring an invitation.

Scenario: Self-join room as viewer

• WHEN an authenticated non-member sends POST /api/rooms/{room_id}/join
• THEN the system SHALL create a room_members record with role "viewer"
• AND update room's member_count
• AND record added_by as the joining user's own ID
• AND record added_at timestamp
• AND return status 200 with the new membership details

Scenario: Self-join when already a member

• WHEN an existing member sends POST /api/rooms/{room_id}/join
• THEN the system SHALL return status 409 with "Already a member of this room"
• AND include current membership details in response

Scenario: Self-join archived room

• WHEN a user attempts to join an archived room
• THEN the system SHALL return status 400 with "Cannot join archived room"

Requirement: Manage Room Membership (MODIFIED)

The system SHALL allow room owners and editors to manage members. Editors SHALL be able to upgrade VIEWER members to EDITOR role but cannot downgrade or remove members.

Scenario: Editor upgrades viewer to editor (NEW)

• WHEN a room editor sends PATCH /api/rooms/{room_id}/members/{user_id} with:

  {
    "role": "editor"
  }
  

• AND the target user is currently a viewer
• THEN the system SHALL update the member's role to "editor"
• AND record the change in audit log
• AND return status 200 with updated member details

Scenario: Editor attempts to downgrade member

• WHEN a room editor attempts to change a member's role to a lower role (editor → viewer)
• THEN the system SHALL return status 403 with "Editors can only upgrade members"

Scenario: Editor attempts to remove member

• WHEN a room editor attempts to remove a member
• THEN the system SHALL return status 403 with "Only owner can remove members"

Scenario: Editor attempts to set owner role

• WHEN a room editor attempts to change a member's role to "owner"
• THEN the system SHALL return status 403 with "Only owner can transfer ownership"

Requirement: Room Access Control (MODIFIED)

The system SHALL enforce role-based access control. Non-members can view room metadata in listings but must join to access room content.

Scenario: Non-member views room in list (NEW)

• WHEN a non-member requests room list via GET /api/rooms
• THEN the system SHALL include all rooms with basic metadata
• AND set is_member: false and current_user_role: null for non-member rooms

Scenario: Non-member attempts to access room details

• WHEN a non-member sends GET /api/rooms/{room_id}
• THEN the system SHALL return status 403 with "Join room to access details"
• AND include a join_url field pointing to the join endpoint

Scenario: Non-member attempts to access room messages

• WHEN a non-member sends GET /api/rooms/{room_id}/messages
• THEN the system SHALL return status 403 with "Not a member of this room"

ADDED Requirements

Requirement: User Directory Search

The system SHALL provide a searchable user directory for member management, sourced from the users table (populated during login).

Scenario: Search users by name or email

• WHEN a room owner or editor sends GET /api/users/search?q=john
• THEN the system SHALL return users matching the search query
• AND search both display_name and user_id (email) fields
• AND return at most 20 results
• AND include user_id and display_name for each result

Scenario: Search with empty query

• WHEN a user sends GET /api/users/search without query parameter
• THEN the system SHALL return status 400 with "Search query required"

Scenario: Search returns no results

• WHEN a search query matches no users
• THEN the system SHALL return an empty array with status 200