Customer Property Agreement Renewal

Author(s)

• Bishwanath Jana
• Dipak Mourya

Last Updated Date

2025-08-27

---

SRS References

• Agreement Management Module
• Customer Property Mapping
• Notification System
• Scheduler Services

---

Version History

Version	Date	Changes	Author
1.0	2025-08-27	Initial implementation plan	Bishwanath Jana

---

Feature Overview

Objective:
Implement a robust and user-friendly process for renewing Customer Property (CP) agreements in the ERP system. The feature will automate agreement renewal flows, ensure data consistency (especially with CP codes), and provide clear user options for different renewal scenarios.

Scope:

• Handle three main agreement scenarios: No existing agreement, Expired agreement, and Open/Running agreement
• Provide two renewal options for running agreements: future-dated renewal and immediate renewal
• Automatic CP code generation and management
• Integration with existing notification scheduler
• Enhanced agreement reporting with status filters

Dependencies:

• Existing Customer Property Management system
• Agreement Expiry Notification Scheduler
• Property Status Management via Portal Integration
• Email Service for notifications

---

Requirements

1. Agreement Status Detection: System must identify three scenarios - No Agreement, Expired Agreement, and Open/Running Agreement
2. Renewal Options: For running agreements, provide two options - future-dated renewal and immediate expiry with new agreement
3. Automatic CP Management: System must automatically generate new CP codes and close old ones during renewal
4. Rate Modification: Support modification of Rent Rate, Service Charge, and Permission Fee during renewal
5. Scheduler Integration: Implement background scheduler for future-dated agreement activation
6. Agreement Report Enhancements: Add status filters (Open, Expired, Released) with color coding
7. Audit Trail: Maintain complete audit trail for all agreement modifications and renewals
8. Data Consistency: Ensure seamless integration with existing property status management and portal updates
9. Performance: Handle renewal operations within acceptable time limits without system performance impact

---

Design Specifications

• UI/UX Design:

  

• Data Models:
  Enhanced existing models to support agreement renewal functionality.

  // Enhanced Agreement Status Enum
  public enum AgreementStatus
  {
      Open,           // Currently active
      Closed,         // Completed normally
      Released,       // Terminated early
      Expired,        // Past end date
      PendingActivation // Future-dated, waiting for scheduler
  }
  
  // Enhanced CP Struct for Renewal Support
  public class CPStruct
  {
      // Existing fields...
      public DateTime? ScheduledActivationDate { get; set; }
      public string? PendingCPCode { get; set; }
      public bool HasPendingRenewal { get; set; }
  }
  
  // Agreement Renewal Request Model
  public class AgreementRenewalRequest
  {
      public string CustomerId { get; set; }
      public string PropertyCode { get; set; }
      public string CPCode { get; set; }
      public RenewalType RenewalType { get; set; }
      public DateTime NewStartDate { get; set; }
      public DateTime NewEndDate { get; set; }
      public string PeriodOfAgreement { get; set; }
      public DateTime ExecutionDate { get; set; }
      public decimal RentRate { get; set; }
      public decimal ServiceChargeRate { get; set; }
      public decimal PermissionFeeRate { get; set; }
      public string Remarks { get; set; }
  }
  
  public enum RenewalType
  {
      NewAgreement,        // Scenario A - No existing agreement
      ExpiredRenewal,      // Scenario B - Expired agreement
      ImmediateRenewal,    // Scenario C, Option 2 - Force expire current
      FutureRenewal        // Scenario C, Option 1 - Schedule future renewal
  }

• API Interfaces: Updated backend API endpoints (previous renewal endpoints replaced) focusing on distinct Get/Set operations and scheduler integration. Frontend tasks remain unchanged.

  Endpoint	Method	Purpose	Key Parameters	Response	Status Codes
  /api/agreements/data	GET	Fetch current agreement (and status) for a given customer + property	customerId (string, required) propertyCode (string, required)	AgreementData (includes status + summary)	200, 404, 500
  /api/agreements	POST	Create / renew ("Set") agreement (simple or immediate renewal)	AgreementRenewalRequest (body)	AgreementCreateResult (id, cpCode, message)	201, 400, 409, 500
  /api/agreements/{agreementId}/details	GET	Fetch full agreement details (lines, rates, history)	agreementId (guid/string)	AgreementDetails	200, 404, 500
  /api/agreements/{agreementId}/details	POST	Update agreement detail set (rates, period, remarks)	agreementId (guid/string) AgreementDetailsUpdateRequest (body)	AgreementDetailsUpdateResult	200, 400, 409, 500
  /api/agreements/scheduler/pending-activation	GET	(Internal/Admin) List agreements waiting activation	date (optional, date)	List<PendingActivationItem>	200, 204, 500
  (Background Scheduler – no public endpoint)	N/A	Daily activation of future-dated agreements; closes old CP & activates new	-	Logged execution summary	-
  /api/agreement/cp-code/generate	POST	(Retained) Generate new CP code for renewal (if rates changed)	oldCPCode (string) renewalRequest (body)	string (new CP code)	200, 400, 500

• Workflow:
  End-to-end agreement renewal workflow covering all scenarios.

  Phase 1 Workflow (Simple Renewals):

  1. User selects customer from Agreement Report screen
  2. System displays only occupied properties for selected customer
  3. User selects property and initiates renewal process
  4. System detects current agreement status and scenario type
  5. For Scenario A (No Agreement): Generate new agreement directly
  6. For Scenario B (Expired Agreement): Create renewal with new agreement
  7. For Scenario C Option 2 (Immediate Renewal): Expire current agreement and create new one
  8. System automatically generates new CP code if rates are modified
  9. Update property status and billing mappings

  Phase 2 Workflow (Future-Dated Renewals):

  1. For Scenario C Option 1 (Future Renewal): Create agreement with PendingActivation status
  2. Set scheduled activation date and generate pending CP code
  3. Background scheduler checks daily for agreements due for activation
  4. On activation date: Close old agreement, activate new agreement and CP mapping

  Data Flow Sequence:

  Frontend Request → Agreement Status Service → Determine Scenario → 
  Agreement Renewal Service → CP Code Service → Database Updates → 
  Portal Integration → Response

---

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Minimal DB field & enum updates	1.5	None	Add new fields, enum values, indexes if needed
2	Model & DTO adjustments (Agreement / Details)	0.5	Task 1	Align request/response contracts
3	DAL updates (repositories + CP code helper)	2	Task 1	CRUD + CP code generation integration
4	GET agreement data API (/api/agreements/data)	1.5	Task 2,3	Returns status + summary
5	SET agreement (create/renew) API (POST /api/agreements)	2	Task 3,4	Handles immediate renewals
6	GET agreement details API	1	Task 3	Full detail retrieval
7	SET agreement details API	1	Task 6	Update rates/period/remarks
8	CP code generation endpoint integration	0.75	Task 3,5	Reuse existing logic
9	Lightweight activation scheduler job	1	Task 5	Future-dated activation + status flip
11	Unit tests (core services happy paths)	1	Tasks 4-10	Focused minimal coverage
12	Integration test (end-to-end renewal flow)	0.5	Task 11	Single scenario walkthrough
13	Logging & error handling pass	0.5	Tasks 4-12	Standardize responses
14	Documentation & review	0.5	Tasks 1-13	Update SRS + API specs
17	Create a UI screen and page route for agreement renewal with messages if no agreement is available and action buttons	1 hour	None
18	Integrate the minimal API for the property list and implement a filter for it	1 hour	None
19	Display the table and agreement list fetched from the filter	2 hours	None
20	Create a new modal with a two-step stepper for agreement renewal, first step for agreement details view and second step for agreement view	1.5 hours	None
21	Create a modal to fetch agreement details and property and display them in a form so the user can view or update if required	3.5 hours	None
22	Integrate the API to set agreement details and agreement and property details	1.5 hours	None
23	Create a new component for a PDF viewer so users can preview changes, download, and view uploaded documents	2 hours	None
24	Integrate the API to fetch the agreement list	0.75 hours	None
25	Create a modal for users to manually upload the agreement	1 hour	None
26	Integrate the API to submit scanned and signed agreements uploaded in the document section	1 hour	None
27	Convert the HTML code to Base64 format and send it to the navigation endpoint	0.75 hours	None
28	Test all details thoroughly for all required conditions to ensure everything is working properly	3 hours	None
29	Overall Total	32 hours	-	Backend 13h + Frontend 19h

---

Testing & Quality Assurance

• Unit Tests:
  Comprehensive unit testing for all core services and business logic components.

  • Agreement Status Detection Service tests for all scenario types
  • Agreement Renewal Service tests for each renewal type
  • CP Code Management Service tests for generation and lifecycle operations
  • Database operation tests with transaction rollback scenarios
  • Validation tests for request models and business rules

• Integration Tests:
  End-to-end testing of complete renewal workflows and system integrations.

  • Complete renewal workflow testing for all scenarios (A, B, C-Option1, C-Option2)
  • Database transaction consistency testing across multiple tables
  • Portal integration testing for property status updates
  • Email service integration testing
  • Background scheduler integration with database operations

• Acceptance Criteria:
  Feature completion criteria based on functional requirements.

  • All three agreement scenarios (No Agreement, Expired, Running) handled correctly
  • Both renewal options for running agreements work as specified
  • Automatic CP code generation and old CP closure functions properly
  • Rate modifications during renewal work without data inconsistency
  • Background scheduler activates future-dated agreements on correct dates
  • (Notification suppression not in scope for this document)
  • Agreement reports display correct status filters and color coding
  • All database operations maintain referential integrity
  • Performance meets acceptable response time requirements

• Testing Tools:
  Standard testing framework and tools used in the existing project.

  • xUnit for unit testing
  • Moq for service mocking
  • Entity Framework In-Memory Database for integration testing
  • Postman for API endpoint testing
  • Custom database transaction testing utilities

---

Deployment Considerations

• Configuration Changes:
  Minimal configuration changes required due to leveraging existing infrastructure.

  • Background service registration for Agreement Activation Scheduler
  • Database connection string validation for new table columns
  • Email template updates for agreement renewal (if required)
  • Logging configuration for new services and schedulers

• Rollout Plan:
  Phased implementation approach to minimize risk and ensure system stability.

  Phase 1 Rollout (Weeks 1-6):

  • Deploy database schema updates during maintenance window
  • Release core agreement renewal services for simple scenarios
  • Enable enhanced agreement reports with status filters
  • Conduct user acceptance testing with limited user group

  Phase 2 Rollout (Weeks 7-8):

  • Deploy background scheduler service
  • Enable future-dated renewal functionality
  • Update notification scheduler with suppression logic
  • Full feature rollout to all users

  Migration Strategy:

  • Existing agreement data requires no migration
  • New database columns with default values ensure backward compatibility
  • Agreement status values updated through normal application logic

---

Risks & Mitigations

Risk	Impact	Likelihood	Mitigation Strategy
CP Code Generation Conflicts	High	Medium	Implement robust unique code generation with retry logic and fallback mechanisms
Data Consistency During Renewal	High	Low	Use database transactions for all renewal operations and implement rollback procedures
Background Scheduler Reliability	Medium	Medium	Implement comprehensive error handling, logging, and monitoring for scheduler services
Performance Impact on Large Datasets	Medium	Low	Optimize database queries, implement proper indexing, and conduct load testing
Integration Issues with Portal	Medium	Low	Thorough testing of existing portal integration endpoints and error handling
User Training and Adoption	Low	Medium	Provide comprehensive documentation and training materials for different renewal scenarios

---

Review & Approval

• Reviewer:
  Ayon Das

• Approval Date:
  2025-09-02

---

Notes

• This implementation plan focuses on backend services and API development
• Frontend components and UI/UX implementation are out of scope for this document
• The phased approach allows for early delivery of simple renewal scenarios while complex scheduler-dependent functionality is developed
• All new services leverage existing infrastructure and patterns to minimize development risk
• Comprehensive testing strategy ensures reliability and data consistency throughout the renewal process