Feature: Add an 'Edit Song' Form

[david]

1. User Story & Rationale

• Parent Epic Issue: Ability to edit songs #75
• DDD Subdomain: Songs
• User Story: As an Administrator, I want to access an editing interface for any song directly from the song list so that I can quickly make necessary corrections.
• Rationale: This feature provides the primary user interface for administrators to modify song attributes, which is a core capability of the "Ability to Edit Songs" epic.

2. Acceptance Criteria (BDD Scenarios)

Scenario 1: Successful Song Edit

• Scenario Name: Administrator successfully edits and saves a song.
• GIVEN: An administrator is viewing the list of songs.
• WHEN: The administrator clicks the "Edit" button for a specific song.
• AND: They modify the title and body in the form.
• AND: They click the "Save" button.
• THEN: The system saves the changes and redirects the administrator back to the song list.
• AND: The updated title is visible in the song list.
• AND: A confirmation message like "Song updated successfully" is displayed.

Scenario 2: Unauthorized User Access

• Scenario Name: A non-administrator attempts to access the edit form.
• GIVEN: A user is logged in who is not an administrator.
• WHEN: The user attempts to navigate directly to the "Edit Song" URL.
• THEN: The system denies access and redirects the user to an appropriate error page (e.g., "Unauthorized").

Scenario 3: Cross-Organization Access by Administrator

• Scenario Name: An administrator from one organization attempts to edit a song from another.
• GIVEN: An administrator for "Organization A" is logged in.
• AND: A song exists that belongs to "Organization B".
• WHEN: The administrator from "Organization A" attempts to access the "Edit Song" page for the song belonging to "Organization B".
• THEN: The system denies access and returns a "Not Found" or "Unauthorized" error.

Scenario 4: Invalid Song Edit

• Scenario Name: Administrator attempts to save a song with invalid data.
• GIVEN: An administrator is on the "Edit Song" form.
• WHEN: The administrator clears the title field, leaving it blank.
• AND: They click the "Save" button.
• THEN: The system does not save the changes.
• AND: It displays a validation error message, such as "Title can't be blank," next to the title field.
• AND: The form remains on the screen with the invalid data entered by the user.

3. UI/UX Flow

1. Navigate to Song List: The Administrator navigates to the /admin/songs page, which displays a table of all songs.
2. Initiate Edit: The Administrator clicks the "Edit" button next to a song in the list.
3. Display Edit Form: The system navigates to /admin/songs/:id/edit. The page displays a form with the following fields pre-populated with the song's current data:
   • Title (text input)
   • Body (textarea)
4. Modify and Save: The Administrator modifies the Title and/or Body and clicks the "Save" button.
5. Confirm and Redirect: The system saves the changes to the database, displays a flash message saying "Song updated successfully," and redirects the Administrator back to the song list at /admin/songs.
6. Cancel Edit: If the Administrator clicks the "Cancel" button, the system discards any changes and redirects them back to the song list at /admin/songs.

4. Permissions

• Administrator:
  • Can access the "Edit Song" page.
  • Can view and modify the title and body fields.
  • Can save changes to a song within their own organization.
• Congregation Member:
  • Cannot access the "Edit Song" page.
  • Any attempt to navigate to the edit URL will result in an "Unauthorized" error.
• Unauthenticated User:
  • Cannot access the "Edit Song" page.
  • Any attempt to navigate to the edit URL will result in a redirection to the login page.

5. Out of Scope

• Creating new songs: This will be handled in a separate feature.
• Deleting songs: This will be handled in a separate feature.
• Displaying a preview of the song's body in the song list: This will be handled in issue Feature: Display song body preview in the song list #87.

[david]

Technical Design: Add an 'Edit Song' Form

• Feature Specification: Link to Feature Specification

---

Affected Contexts & Modules

• CMS.Songs: This context will be modified to include a new function, update_song/2, responsible for handling the business logic of updating a song. The existing get_song!/2 function will be used to fetch the song for the form.
• CMSWeb.SongLive.Admin.Form: This new LiveView will provide the user interface for editing a song. It will manage the form state, handle user input, and display validation errors.
• CMSWeb.SongLive.Admin.Index: This existing LiveView will be modified to add an "Edit" button to the song list, linking to the new form.
• CMSWeb.Router: The router will be updated to include a new route, /admin/songs/:id/edit, which will direct requests to the CMSWeb.SongLive.Admin.Form.

---

Database Schema Changes

Based on the feature specification, no changes are needed for the database schema, as we are only editing existing Song records.

---

Key Functions & Logic

CMS.Songs

• update_song(scope, song, attrs)
  • Responsibility: Takes a %Song{} struct and a map of attributes, validates them using the existing Song.changeset/3 function, and updates the song in the database. It will enforce the organization_id from the scope to ensure an administrator can only update songs within their own organization.

CMSWeb.SongLive.Admin.Form

• mount(params, _session, socket)
  • Responsibility: Fetches the song using CMS.Songs.get_song!/2 and initializes a changeset for the form. It will handle the :edit action.
• render(assigns)
  • Responsibility: Renders the "Edit Song" form, including fields for title and body. It will use the <.form> component and bind it to the changeset.
• handle_event("validate", %{"song" => song_params}, socket)
  • Responsibility: Validates the form data in real-time as the user types, providing immediate feedback on any errors.
• handle_event("save", %{"song" => song_params}, socket)
  • Responsibility: Calls CMS.Songs.update_song/3 to save the changes. On success, it will display a flash message and redirect to the song list. On failure, it will re-render the form with the validation errors.

---

Security Analysis

• Data Scoping: All database queries will be strictly scoped to the organization_id of the currently logged-in administrator. The CMS.Songs.get_song!/2 function already ensures that a song is fetched only if it belongs to the administrator's organization. The CMS.Songs.update_song/3 function will use the CMS.Songs.Song.changeset/3 function, which also enforces the organization_id from the scope, preventing any possibility of cross-organization data modification.

• Permissions: Access to the "Edit Song" form will be restricted to administrators. The CMSWeb.Router will enforce this by placing the /admin/songs/:id/edit route within the :admin_only_access pipeline. This pipeline includes the require_admin_user plug, which will deny access to any user who is not an administrator, effectively preventing unauthorized access as described in the BDD scenarios.

• Input Validation: All user-submitted data will be validated using the CMS.Songs.Song.changeset/3 function. This will prevent invalid data, such as a blank title, from being saved to the database. The form will display specific error messages to the user, ensuring a secure and user-friendly experience.

This feature does not introduce any new types of security vulnerabilities, and the existing security model of the application is sufficient to protect against the risks identified in the feature specification.

---

Testing Strategy (TDD Plan)

BDD Scenario: Administrator successfully edits and saves a song.

• UI/LiveView Test:
  • A feature test will simulate an administrator navigating to the edit page for a song.
  • It will fill in new values for the title and body fields and submit the form.
  • The test will assert that the user is redirected back to the song list and that a success flash message is displayed.
  • Finally, it will assert that the updated song title is present in the rendered list.
• Integration Test:
  • An integration test for CMS.Songs.update_song/3 will be created.
  • It will call the function with a valid scope, an existing song, and a map of new attributes.
  • The test will assert that the function returns {:ok, %Song{}} and that the song's attributes have been updated in the database.
• Unit Test:
  • No new unit tests are required for this scenario, as the existing CMS.Songs.Song.changeset/3 is already tested.

BDD Scenario: Unauthorized user attempts to access the edit form.

• UI/LiveView Test:
  • A feature test will simulate a non-administrator user attempting to navigate directly to the /admin/songs/:id/edit URL.
  • The test will assert that the user is redirected to an unauthorized page and that no part of the edit form is rendered.

BDD Scenario: An administrator from one organization attempts to edit a song from another.

• UI/LiveView Test:
  • A feature test will be created where an administrator from "Organization A" attempts to access the edit page for a song belonging to "Organization B".
  • The test will assert that the server responds with a "Not Found" or "Unauthorized" error, preventing the user from seeing the form.
• Integration Test:
  • An integration test will call CMS.Songs.get_song!/2 with a scope for "Organization A" and an ID for a song from "Organization B".
  • The test will assert that an Ecto.NoResultsError is raised.

BDD Scenario: Administrator attempts to save a song with invalid data.

• UI/LiveView Test:
  • A feature test will simulate an administrator submitting the edit form with a blank title.
  • The test will assert that the form is re-rendered with a validation error message next to the title field and that the live_action remains :edit.
• Integration Test:
  • An integration test for CMS.Songs.update_song/3 will be created, passing in invalid attributes (e.g., a blank title).
  • The test will assert that the function returns {:error, %Ecto.Changeset{}} and that the changeset contains the expected validation errors.

---

Open Questions & Blockers

Open Questions

• There are no open technical questions at this time. The feature appears to be well-defined, and the implementation path is clear based on existing application patterns.

Blockers

• There are no technical blockers for this feature. Implementation can begin as soon as this technical design is approved.

---

Development & Verification Steps

1. Create the Form LiveView:

   • Create the lib/cms_web/live/song_live/admin/form.ex file.
   • Implement the mount/3, render/1, and handle_event/3 functions as outlined in the "Key Functions & Logic" section.

2. Write Failing Integration Test for update_song/3:

   • In a new test file, test/cms/songs_test.exs, write a test for the CMS.Songs.update_song/3 function.
   • The test should call the function with valid attributes and assert that it returns {:ok, %Song{}}. This test will fail because the function does not yet exist.

3. Implement update_song/3:

   • In lib/cms/songs.ex, create the update_song/3 function.
   • The function should use the existing Song.changeset/3 to validate the attributes and then update the song using Repo.update/1.
   • Run the integration test again to ensure it passes.

4. Write Failing LiveView Test for the Edit Form:

   • In a new test file, test/cms_web/live/song_live/admin/form_test.exs, write a feature test that simulates an administrator successfully editing a song.
   • The test should navigate to the edit page, fill in the form, and submit it.
   • It should assert that the user is redirected to the song list and that a success flash message is displayed. This test will fail because the route and the form are not yet fully implemented.

5. Implement the Route and Form Logic:

   • Add the /admin/songs/:id/edit route to lib/cms_web/router.ex.
   • In lib/cms_web/live/song_live/admin/form.ex, complete the implementation of the handle_event("save", ...) function to call CMS.Songs.update_song/3.
   • Run the LiveView test again to ensure it passes.

6. Implement Remaining Scenarios:

   • Follow the same TDD cycle for the remaining BDD scenarios:
     • Write a failing test for the scenario.
     • Write the code to make the test pass.
     • Refactor as needed.

7. Final Verification:

   • Once all scenarios are implemented and all tests are passing, run the entire test suite with mix test to check for any regressions.
   • Finally, run mix format to ensure the code is correctly formatted.