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

Implementation Tasks

1. Database Schema

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

2. Backend API Implementation

2.1 Module Structure

• 2.1.1 Create app/modules/chat_room/ directory structure:
  • __init__.py (export public interfaces)
  • models.py (SQLAlchemy models)
  • schemas.py (Pydantic request/response models)
  • router.py (FastAPI routes)
  • services/ subdirectory
  • dependencies.py (room access validators)

2.2 Models Implementation

• 2.2.1 Create IncidentRoom SQLAlchemy model
• 2.2.2 Create RoomMember SQLAlchemy model
• 2.2.3 Create RoomTemplate SQLAlchemy model
• 2.2.4 Define Enum types for incident_type, severity, status, role
• 2.2.5 Add relationship definitions between models

2.3 Schemas Implementation

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

2.4 Services Implementation

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

2.5 Router Implementation

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

2.6 Dependencies and Middleware

• 2.6.1 Create get_current_room dependency for room access validation
• 2.6.2 Create require_room_permission dependency with permission levels
• 2.6.3 Create validate_room_owner dependency for owner-only operations
• 2.6.4 Create require_admin dependency for admin-only operations
• 2.6.5 Create get_user_effective_role dependency (considers admin override)
• 2.6.6 Integrate with auth module's get_current_user

3. Business Logic Implementation

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

4. Testing

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

5. Documentation

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

6. Integration

• 6.1 Register router in main FastAPI app
• 6.2 Add room module to app initialization
• 6.3 Ensure proper dependency injection with auth module
• 6.4 Prepare for future WebSocket integration (room-based channels)