# 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:
  ```json
  {
    "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