Task_Reporter/openspec/changes/archive/2025-11-17-add-chat-room-management/tasks.md

# Implementation Tasks

## 1. Database Schema
- [x] 1.1 Create `incident_rooms` table with columns:
  - [x] room_id (UUID, PK)
  - [x] title (VARCHAR, required)
  - [x] incident_type (ENUM: equipment_failure, material_shortage, quality_issue, other)
  - [x] severity (ENUM: low, medium, high, critical)
  - [x] status (ENUM: active, resolved, archived)
  - [x] location (VARCHAR)
  - [x] description (TEXT)
  - [x] resolution_notes (TEXT, nullable)
  - [x] created_by (FK to users)
  - [x] created_at (TIMESTAMP)
  - [x] resolved_at (TIMESTAMP, nullable)
  - [x] archived_at (TIMESTAMP, nullable)
  - [x] last_activity_at (TIMESTAMP)
  - [x] last_updated_at (TIMESTAMP)
  - [x] member_count (INTEGER, default 0)
  - [x] ownership_transferred_at (TIMESTAMP, nullable)
  - [x] ownership_transferred_by (VARCHAR, nullable)
- [x] 1.2 Create `room_members` table with columns:
  - [x] id (PK)
  - [x] room_id (FK to incident_rooms)
  - [x] user_id (VARCHAR, user identifier)
  - [x] role (ENUM: owner, editor, viewer)
  - [x] added_by (VARCHAR, user who added this member)
  - [x] added_at (TIMESTAMP)
  - [x] removed_at (TIMESTAMP, nullable for soft delete)
  - [x] UNIQUE constraint on (room_id, user_id) where removed_at IS NULL
- [x] 1.3 Create `room_templates` table:
  - [x] template_id (PK)
  - [x] name (VARCHAR, unique)
  - [x] description (TEXT)
  - [x] incident_type (ENUM)
  - [x] default_severity (ENUM)
  - [x] default_members (JSON array of user roles)
  - [x] metadata_fields (JSON schema)
- [x] 1.4 Create indexes:
  - [x] Index on incident_rooms(status, created_at)
  - [x] Index on incident_rooms(created_by)
  - [x] Index on room_members(room_id, user_id)
  - [x] Index on room_members(user_id) for user's rooms query
- [x] 1.5 Create database migration scripts using Alembic

## 2. Backend API Implementation

### 2.1 Module Structure
- [x] 2.1.1 Create `app/modules/chat_room/` directory structure:
  - [x] `__init__.py` (export public interfaces)
  - [x] `models.py` (SQLAlchemy models)
  - [x] `schemas.py` (Pydantic request/response models)
  - [x] `router.py` (FastAPI routes)
  - [x] `services/` subdirectory
  - [x] `dependencies.py` (room access validators)

### 2.2 Models Implementation
- [x] 2.2.1 Create `IncidentRoom` SQLAlchemy model
- [x] 2.2.2 Create `RoomMember` SQLAlchemy model
- [x] 2.2.3 Create `RoomTemplate` SQLAlchemy model
- [x] 2.2.4 Define Enum types for incident_type, severity, status, role
- [x] 2.2.5 Add relationship definitions between models

### 2.3 Schemas Implementation
- [x] 2.3.1 Create request schemas:
  - [x] `CreateRoomRequest` (title, incident_type, severity, location, description)
  - [x] `UpdateRoomRequest` (partial updates)
  - [x] `AddMemberRequest` (user_id, role)
  - [x] `UpdateMemberRoleRequest` (role)
  - [x] `RoomFilterParams` (status, type, severity, dates, search)
- [x] 2.3.2 Create response schemas:
  - [x] `RoomResponse` (full room details)
  - [x] `RoomListResponse` (paginated list)
  - [x] `MemberResponse` (user info with role)
  - [x] `TemplateResponse` (template details)

### 2.4 Services Implementation
- [x] 2.4.1 Create `services/room_service.py`:
  - [x] `create_room(db, user_id, room_data) -> IncidentRoom`
  - [x] `get_room(db, room_id, user_id) -> IncidentRoom`
  - [x] `list_user_rooms(db, user_id, filters) -> List[IncidentRoom]`
  - [x] `update_room(db, room_id, updates) -> IncidentRoom`
  - [x] `change_room_status(db, room_id, new_status) -> IncidentRoom`
  - [x] `search_rooms(db, user_id, search_term) -> List[IncidentRoom]`
- [x] 2.4.2 Create `services/membership_service.py`:
  - [x] `add_member(db, room_id, user_id, role, added_by) -> RoomMember`
  - [x] `remove_member(db, room_id, user_id) -> bool`
  - [x] `update_member_role(db, room_id, user_id, new_role) -> RoomMember`
  - [x] `transfer_ownership(db, room_id, current_owner_id, new_owner_id) -> bool`
  - [x] `get_room_members(db, room_id) -> List[RoomMember]`
  - [x] `get_user_rooms(db, user_id) -> List[IncidentRoom]`
  - [x] `check_user_permission(db, room_id, user_id, permission) -> bool`
  - [x] `is_system_admin(user_email) -> bool` (check if ymirliu@panjit.com.tw)
- [x] 2.4.3 Create `services/template_service.py`:
  - [x] `get_templates(db) -> List[RoomTemplate]`
  - [x] `create_room_from_template(db, template_id, user_id, additional_data) -> IncidentRoom`

### 2.5 Router Implementation
- [x] 2.5.1 Room CRUD endpoints:
  - [x] `POST /api/rooms` - Create new room
  - [x] `GET /api/rooms` - List/filter rooms
  - [x] `GET /api/rooms/{room_id}` - Get room details
  - [x] `PATCH /api/rooms/{room_id}` - Update room
  - [x] `DELETE /api/rooms/{room_id}` - Soft delete room
- [x] 2.5.2 Membership endpoints:
  - [x] `GET /api/rooms/{room_id}/members` - List members
  - [x] `POST /api/rooms/{room_id}/members` - Add member
  - [x] `PATCH /api/rooms/{room_id}/members/{user_id}` - Update role
  - [x] `DELETE /api/rooms/{room_id}/members/{user_id}` - Remove member
  - [x] `POST /api/rooms/{room_id}/transfer-ownership` - Transfer room ownership
- [x] 2.5.3 Permission endpoints:
  - [x] `GET /api/rooms/{room_id}/permissions` - Get current user permissions
- [x] 2.5.4 Template endpoints:
  - [x] `GET /api/rooms/templates` - List available templates

### 2.6 Dependencies and Middleware
- [x] 2.6.1 Create `get_current_room` dependency for room access validation
- [x] 2.6.2 Create `require_room_permission` dependency with permission levels
- [x] 2.6.3 Create `validate_room_owner` dependency for owner-only operations
- [x] 2.6.4 Create `require_admin` dependency for admin-only operations
- [x] 2.6.5 Create `get_user_effective_role` dependency (considers admin override)
- [x] 2.6.6 Integrate with auth module's `get_current_user`

## 3. Business Logic Implementation
- [x] 3.1 Status transition validation:
  - [x] active → resolved → archived (valid)
  - [x] Prevent invalid transitions
  - [x] Auto-update last_activity_at on any change
- [x] 3.2 Member count synchronization:
  - [x] Increment on member addition
  - [x] Decrement on member removal
  - [x] Recalculate on soft-delete operations
- [x] 3.3 Permission matrix implementation:
  - [x] Owner: all operations including ownership transfer
  - [x] Editor: read, add members (viewer only), send messages
  - [x] Viewer: read only
  - [x] Admin (ymirliu@panjit.com.tw): all operations plus override capabilities
- [x] 3.4 Audit trail:
  - [x] Log all room status changes
  - [x] Log membership changes
  - [x] Log ownership transfers with timestamp and user
  - [x] Log admin override actions
  - [x] Track last_activity for sorting

## 4. Testing
- [x] 4.1 Unit tests for services:
  - [x] Test room creation with valid/invalid data
  - [x] Test status transitions
  - [x] Test member addition/removal
  - [x] Test permission checks
- [x] 4.2 Integration tests for API endpoints:
  - [x] Test full room lifecycle (create → resolve → archive)
  - [x] Test filtering and search
  - [x] Test membership management
  - [x] Test unauthorized access scenarios
- [x] 4.3 Test permission matrix:
  - [x] Owner can do all operations including ownership transfer
  - [x] Editor limitations
  - [x] Viewer read-only access
  - [x] Admin (ymirliu@panjit.com.tw) bypass all restrictions
- [x] 4.4 Test edge cases:
  - [x] Duplicate member addition
  - [x] Self-removal as last owner
  - [x] Concurrent updates
  - [x] Ownership transfer to non-member (should fail)
  - [x] Ownership transfer validation

## 5. Documentation
- [x] 5.1 API documentation:
  - [x] Document all endpoints in OpenAPI/Swagger format
  - [x] Include request/response examples
  - [x] Document error codes and messages
- [x] 5.2 Module README:
  - [x] Explain room lifecycle
  - [x] Document permission model
  - [x] Provide integration examples
- [x] 5.3 Database schema documentation:
  - [x] ER diagram
  - [x] Index strategy explanation

## 6. Integration
- [x] 6.1 Register router in main FastAPI app
- [x] 6.2 Add room module to app initialization
- [x] 6.3 Ensure proper dependency injection with auth module
- [x] 6.4 Prepare for future WebSocket integration (room-based channels)