CSC/ECE 517 Spring 2025 - E2541. Refactor Student Teams Functionality

From Expertiza_Wiki
Jump to navigation Jump to search

CSC/ECE 517 Spring 2025 – Refactor Student Teams Functionality

Team Members

  • James Patel
  • Sweekar Burji
  • Isaac Taylor 

1. Expertiza Overview

Expertiza is a modular peer‑review and assignment management platform. Core modules:

  • Assignments: creation, distribution, deadlines
  • Reviews: peer‑review workflows, rubric configuration
  • Teams: student grouping and collaboration
  • Feedback & Grading: role‑based score/comment interfaces

Role‑based access controls define permissions for instructors, TAs, and students, ensuring secure, fine‑grained data access.

2. Project Overview

Refactor the **Student Teams** feature to:

  1. Improve maintainability
  2. Clarify domain concepts
  3. Enforce precise, assignment‑specific membership mappings

Align data model and business logic with a clear “Participant” abstraction, reducing complexity and eliminating duplication.

3. Problem Statement

Legacy implementation issues:

  • Generic Mapping Table: `teams_users` simply relates `user_id` ↔ `team_id`, allowing cross‑assignment memberships without context.
  • Ambiguous Naming & Raw SQL: unclear model relationships drive developers to bypass ActiveRecord, raising security and maintainability concerns.
  • Testing Gaps & Duplication: sparse specs around membership logic; duplicated code in controllers and models increases risk of regressions.

4. Design Goals & Objectives

  1. Domain Clarity
    1. Rename `teams_users` → `teams_participants`
    2. Replace `user_id` with `participant_id` to tie membership to a `Participant` record
  2. Data Integrity
    1. Add DB constraints: FKs to `participants` & `teams`; unique index on `[:participant_id, :team_id]`
    2. Enforce presence and uniqueness via ActiveRecord validations
  3. Code Quality & Maintainability
    1. Extract membership logic into `TeamsParticipant` model & new `TeamsParticipantsController`
    2. Apply Single Responsibility Principle—controllers for HTTP, models for business rules
  4. Testing & Verification
    1. Expand RSpec coverage to ≥ 90% for refactored components
    2. Consolidate logic (e.g., `get_team_members`, `add_member_to_invited_team`) on `TeamsParticipant`
  5. Success Metrics
  • Test coverage ↑ (SimpleCov)
  • Cyclomatic complexity ↓ (CodeClimate)
  • No CodeQL warnings

5. System Architecture Overview

5.1 Data Flow (MVC Pattern)

[ Models ] → [ Controllers ] → [ Views ]
      ↑                ↓
  ActiveRecord     HTTP responses & redirects
  validations

5.2 Entity‑Relationship Diagram (ASCII)

+-------------+      +-------------------+      +-------------+
| Participant |1----*| TeamsParticipant  |*----1|     Team    |
+-------------+      +-------------------+      +-------------+
      (id)            (participant_id)           (id, name,…)
                       (team_id)
                       (duty_id)
                       (status)

5.3 Schema Changes (Rails Migrations)

Rename table
rename_table :teams_users, :teams_participants
Add participant FK
add_column :teams_participants, :participant_id, :bigint, null: false
add_foreign_key :teams_participants, :participants
Remove old column
remove_column :teams_participants, :user_id
Unique index
add_index :teams_participants, [:participant_id, :team_id], unique: true

6. Detailed Component Design

6.1 Models

TeamsParticipant

  • Attributes: `team_id`, `participant_id`, `duty_id` (optional), `pair_programming_status`
  • Associations:
    • `belongs_to :team`
    • `belongs_to :participant`
    • `belongs_to :duty, optional: true`
  • Validations:
    • presence of `team_id` and `participant_id`
    • uniqueness of `participant_id` scoped to `team_id`
  • Class Methods:
    • `.team_empty?(team_id)`
    • `.add_member_to_invited_team(token, participant_id)`
    • `.get_team_members(team_id)`
    • `.get_teams_for_participant(participant_id)`

Participant

  • Rename association `team_user` → `teams_participant`
  • Update `has_many :teams_participants`, adjust dependent destroy logic

6.2 Controllers

TeamsParticipantsController

  • Actions: `index`, `new`, `create`, `destroy`, `destroy_selected`, `update_duties`
  • Responsibilities:
    • Handle membership lifecycle (create, delete, bulk remove, duty update)
    • Strong params: permit only `:participant_id`, `:team_id`, duty fields
    • Render HTML or JSON with appropriate flash/redirects

JoinTeamRequestsController

  • Refactored to use `TeamsParticipant` for listing requests and popups
  • Simplified business logic—no raw SQL, uses ActiveRecord scopes

6.3 Views (UI)

  • Replace `user.name` with `participant.full_name` in student teams pages
  • Render duty assignment via partial `_duty_form.html.erb`
  • Include before/after screenshots in documentation to illustrate updates

7. Testing Strategy

7.1 Unit Testing (RSpec Model Specs)

  • **TeamsParticipant**: test associations, validations, and class methods

7.2 Controller Testing

  • **TeamsParticipantsController**: verify HTTP codes, redirects, flash messages, and error handling

7.3 Integration & System Testing

  • **Capybara System Specs**: workflows for team creation, invitations, duty assignment, member removal; UI assertions

7.4 Fixtures & Factories

  • Update `FactoryBot` definitions: replace `:user_team` with `:teams_participant`
  • Use shared contexts for assignments, participants, and teams

8. Design Rationale & Impact

  • Single Responsibility: clear separation of concerns between controllers and models
  • Domain Alignment: “participant” abstraction captures assignment context
  • Security & Quality: ActiveRecord replaces raw SQL; CodeQL scans pass cleanly
  • Maintainability: centralized logic enables easier future enhancements
  • Risks & Mitigations:
    • Migration complexity → write reversible migrations, schedule maintenance window
    • Data integrity → pre‑validate existing records before enforcing constraints

9. References