Complete Agreements Wizard: Enhancements & Implementation

by SLV Team 58 views
Complete Agreements Add/Edit Wizard: Enhancements & Implementation

Hey guys! Today, let's dive deep into the enhancements and implementation of the Complete Agreements Add/Edit Wizard. This is a crucial step in making our agreements management system more robust and user-friendly. We're going to break down the requirements, implementation details, and everything else you need to know. So, buckle up, and let's get started!

Overview

The main goal here is to complete the agreements CRUD UI (Create, Read, Update, Delete User Interface) with a multi-step wizard. This wizard will be essential for creating and versioning agreements, including setting up commission rules. Think of it as a streamlined process that guides users through each step, making everything much easier to manage. This enhancement ensures we have a production-ready workflow, which is super important for our team's efficiency and accuracy.

Context

Previously, in Issue #24, we laid the groundwork by implementing the basic agreements listing and delete functionality. The "Add Agreement" button was intentionally kept disabled, displaying a "Coming Soon" message. This was because the create/edit workflow needed more attention. Now, we're picking up where we left off. This enhancement is all about completing the full agreements CRUD workflow with a polished, multi-step wizard. It's about bringing that "Coming Soon" feature to life and making it a core part of our system.

User Requirements

To make sure we're building something that truly meets our users' needs, we've identified some key requirements:

  1. Multi-step wizard: The process should be broken down into manageable steps. Specifically, we'll have Agreement details (Step 1) + Rules configuration (Step 2). This makes the whole thing less overwhelming and more intuitive.
  2. Immutable versioning: Instead of directly editing agreements, we'll create new versions. This is crucial for maintaining a clear audit trail. It ensures we can always see the history of changes and who made them.
  3. Basic rules UI: We need a user interface that allows for the configuration of essential rules. This includes fields like rule_name, revenue_component, commission_rate_bps, attribution_method, and validator_key_pattern. Think of it as the core settings for defining how commissions are calculated and distributed.

These requirements are the backbone of our development. They ensure we're not just building a feature, but a solution that truly works for our users.

Implementation Details

Let's get into the nitty-gritty of how we're going to build this thing. We'll break it down step by step.

Step 1: Agreement Details Form

This is where users will input the basic information about the agreement. Here's what the form will include:

  • Partner selection: An autocomplete dropdown to select from a list of active partners. This makes it easy to find and select the right partner.
  • Agreement name: A required text field for the name of the agreement. This should be something descriptive and easy to identify.
  • Effective dates: A required start date and an optional end date. If no end date is provided, we'll assume the agreement is ongoing.
  • Status selection: A dropdown to choose the status of the agreement. Options include DRAFT, ACTIVE, SUSPENDED, and TERMINATED. This helps manage the lifecycle of the agreement.
  • Form validation: We'll implement validation to ensure all required fields are filled and that the end date, if provided, is later than the start date. This helps prevent errors and ensures data integrity.

Step 2: Rules Configuration

This step is all about setting up the rules that govern the agreement. Here's what we'll include:

  • Dynamic rules array: Users will be able to add and remove rules as needed. This flexibility is key to accommodating different agreement structures.
  • Rule details: Each rule will require the following:
    • rule_name: A descriptive name for the rule (text input). This helps in easily identifying the purpose of the rule.
    • revenue_component: A dropdown with options like EXEC_FEES, MEV_TIPS, VOTE_REWARDS, and COMMISSION. This specifies what type of revenue the rule applies to.
    • commission_rate_bps: A number input for the commission rate in basis points (0-10000). We'll display this as a percentage for clarity.
    • attribution_method: A dropdown with options like CLIENT_REVENUE, STAKE_WEIGHT, and FIXED_SHARE. This determines how the commission is attributed.
    • validator_key_pattern: An optional SQL LIKE pattern for filtering validators. This allows for more granular control over which validators the rule applies to.
  • Minimum 1 rule required: We'll enforce that at least one rule must be added to submit the agreement. This ensures that agreements are properly configured.
  • Add/remove rule buttons: Users will have buttons to dynamically add or remove rules as needed. This makes it easy to adjust the agreement structure.

Immutable Versioning Pattern

This is a critical aspect of our implementation. We're going to avoid inline editing of existing agreements. Instead:

  • View Details button: This will open a read-only dialog showing the agreement metadata and all associated rules. It's a way to review the agreement without making changes.
  • Create New Version button: In the view dialog, there will be a button to create a new version. Here's how it works:
    • Copies all data from the existing agreement.
    • Increments the version number.
    • Pre-fills the wizard with the existing data for modification.
    • The user can then modify the details or rules before submitting the new version.

This pattern ensures a clear audit trail and prevents accidental modifications to existing agreements. It's all about maintaining history and control.

UI Flow

Let's walk through the user interface flow to understand how everything will work:

  1. Click "Add Agreement" → Wizard opens (empty, Step 1): This starts the process of creating a new agreement.
  2. Fill agreement details → Click "Next": The user enters the basic information about the agreement.
  3. Add 1+ rules (each rule has all required fields) → Click "Submit": The user configures the commission rules.
  4. Backend creates agreement + rules in a single transaction: This ensures that the agreement and its rules are saved together, maintaining data consistency.
  5. Success message → Grid refreshes with the new agreement: Feedback is important! The user will see a success message, and the agreement list will update.
  6. Click "View" on an existing agreement → Read-only dialog opens: This allows the user to review the agreement details without making changes.
  7. Click "Create New Version" → Wizard opens pre-filled with existing data: This starts the process of creating a new version of the agreement.
  8. Modify fields/rules as needed → Submit as the new version: The user can make changes and submit the new version.

This flow is designed to be intuitive and efficient, guiding users through each step of the process.

Files to Create

We'll need to create a new file for the multi-step wizard:

  • frontend/src/components/AgreementWizard.tsx - This will house the multi-step wizard component, using Material-UI Stepper for a clean and consistent user interface.

Files to Update

We'll also need to update some existing files:

  • frontend/src/pages/AgreementsPage.tsx - We'll enable the add button, wire up the wizard, and add the view dialog functionality.
  • frontend/src/types/index.ts - We'll fix a schema mismatch by adding rule_name and validator_key_pattern to the agreement rule type.
  • frontend/src/services/agreements.ts - We'll verify that the create payload matches the backend schema to ensure data consistency.

Schema Alignment Fixes

It's crucial that our frontend types match the backend schema. We've identified some missing fields in our frontend types that need to be added.

Frontend Types Need Update (frontend/src/types/index.ts):

export interface AgreementRuleCreate {
 agreement_id: string;
 version_number: number;
 rule_name: string; // ADD THIS - currently missing
 revenue_component: RevenueComponent;
 commission_rate_bps: number;
 attribution_method: AttributionMethod;
 validator_key_pattern?: string; // ADD THIS - currently missing
}

The backend already expects these fields in src/api/schemas/agreements.py, so we need to make sure our frontend types are up to date.

Acceptance Criteria

To ensure we've built a solid solution, we've defined a set of acceptance criteria:

  • [ ] Can create a new agreement with 1+ rules
  • [ ] Can create a new agreement with multiple rules
  • [ ] Can view agreement details in a read-only dialog
  • [ ] Can create a new version from an existing agreement (immutable pattern)
  • [ ] Form validates: required fields, date ranges, commission rate 0-10000 bps
  • [ ] Wizard supports Back/Next/Submit navigation with proper step validation
  • [ ] Success/error messages display correctly
  • [ ] Frontend types match backend schema exactly
  • [ ] Agreement grid refreshes after create/update

These criteria are our checklist to make sure we've covered all the bases.

Testing Plan

Testing is key to ensuring the quality of our work. Here's our testing plan:

  • Create an agreement with 1 rule → verify in the database
  • Create an agreement with 3 rules → verify all rules saved
  • Create a new version → verify version incremented, the old version unchanged
  • Validate required fields → verify error messages
  • Validate date range → verify end date > start date enforcement
  • Validate commission rate → verify 0-10000 bps range enforcement
  • Delete agreement → verify status change (soft delete)

This plan covers a range of scenarios to ensure our implementation is robust.

Estimated Effort

We estimate this enhancement will take 1-2 days to complete. This includes development, testing, and any necessary adjustments.

Dependencies

We have some dependencies to be aware of:

  • Backend agreements API (✅ already complete in Issue #20)
  • Partners API (✅ already complete in Issue #23)
  • Frontend setup (✅ Issue #22 complete)

These dependencies are already in place, which streamlines our work.

Blocks

We have one blocking issue:

  • Issue #26 (Testing & Polish) - We should complete this first for full test coverage. This ensures we're building on a solid foundation.

Related Issues

This enhancement is related to the following issues:

  • Enhances #24 (MVP Phase 5b: Partners & Agreements UI)
  • Part of Epic #28 (MVP Admin Dashboard Release)

References

Here are some useful references:

  • Backend API: src/api/routers/agreements.py
  • Backend Schemas: src/api/schemas/agreements.py
  • Existing Frontend: frontend/src/pages/AgreementsPage.tsx
  • Reference Pattern: frontend/src/components/PartnerForm.tsx (similar dialog pattern)

Conclusion

Alright, guys! That's the rundown of the enhancements and implementation for the Complete Agreements Add/Edit Wizard. We've covered everything from the overview and context to the UI flow and testing plan. By following this guide, we can ensure a smooth and successful implementation. Let's get to work and make this feature awesome!