# TODO - Lease Approval Implementation Plan

## Current Status Analysis
Based on codebase review, significant progress has been made. Here's what's already implemented vs remaining tasks.

## Already Completed
- [x] **Database Schema** - Approval fields added to `leases` table (approval_status, timestamps, approved_by, rejection_reason)
- [x] **API Endpoints** - All 4 endpoints created:
  - `POST /api/lease/request-approval` - Tenant initiates lease
  - `POST /api/lease/approve` - Landlord approval  
  - `POST /api/lease/reject` - Landlord rejection
  - `GET /api/lease/pending-approvals` - Landlord dashboard
- [x] **Tenant Invitation Page** - Updated with approval status UI, progress indicators, and status-based messaging
- [x] **Landlord Dashboard** - Added pending approvals section with `getPendingLeaseApprovals()` integration
- [x] **Notification Service** - Basic structure created for lease approval notifications

## Remaining Development Tasks

### 1. Database Migration (HIGH PRIORITY)
- [ ] Create migration SQL file for approval schema changes
- [ ] Run migration to update database with new lease fields
- [ ] Verify database schema matches code expectations

### 2. Lease Finalization Logic (HIGH PRIORITY)  
- [ ] Implement complete lease activation on approval
- [ ] Ensure proper tenant_id linking when approved
- [ ] Set up payment schedules and access rights
- [ ] Update property rental_status to 'occupied'
- [ ] Create lease document generation

### 3. Tenant Invite Status Checking (MEDIUM PRIORITY)
- [ ] Add lease status checking in GET handler of invite page
- [ ] Update UI to show correct status on page load
- [ ] Handle edge cases (multiple leases, expired invites)

### 4. Landlord Dashboard Approval Interface (MEDIUM PRIORITY)
- [ ] Add approve/reject buttons to pending approval cards
- [ ] Create approval modal with lease details
- [ ] Add confirmation dialogs for approve/reject actions
- [ ] Implement real-time updates after approval actions

### 5. Email Notification Implementation (MEDIUM PRIORITY)
- [ ] Complete email template implementation in notificationService
- [ ] Add email sending functionality for approval requests
- [ ] Implement landlord notification when approval needed
- [ ] Add tenant notification for approval/rejection outcomes

### 6. Testing (LOW PRIORITY)
- [ ] Add unit tests for lease approval service functions
- [ ] Create integration tests for API endpoints
- [ ] Add E2E tests for complete approval workflow
- [ ] Test error handling and edge cases
**Tasks:**

- [ ] Create `routes/landlord/approvals/index.tsx`
- [ ] Fetch pending approvals via `/api/lease/pending-approvals`
- [ ] Display detailed property and tenant information
- [ ] Provide approve/reject forms with optional rejection reason
- [ ] Follow Fresh page pattern from `routes/landlord/dashboard/index.tsx`
- [ ] Add navigation link in landlord menu

### 4. E2E Tests ❌ (MEDIUM PRIORITY)

**Status:** Test file exists but doesn't test approval workflow

**Current State:**

- `tests/e2e/lease-creation.spec.ts` exists
- Tests lease acceptance workflow but NOT approval workflow

**Tasks:**

- [ ] Create or update `tests/e2e/lease-approval.spec.ts`
- [ ] Test complete workflow: tenant requests, landlord views/approves, tenant
      sees status
- [ ] Use patterns from `tests/e2e/invite-tenant.spec.ts` and `helpers.ts`
- [ ] Test approval status transitions (pending → approved/rejected)
- [ ] Test notification triggers (when notification service is implemented)
- [ ] Test error cases (unauthorized, invalid lease_id, etc.)

### 5. API Endpoint Validation ⚠️ (LOW PRIORITY)

**Status:** Endpoints exist but may need improvements

**Tasks:**

- [ ] Verify `routes/api/lease/request-approval.ts` has proper error handling
- [ ] Verify `routes/api/lease/approve.ts` has proper error handling
- [ ] Verify `routes/api/lease/reject.ts` has proper error handling
- [ ] Check `routes/api/lease/pending-approvals.ts` returns correct data
      structure
- [ ] Add input validation and error messages
- [ ] Add notification calls when notification service is ready

### 6. Lease Finalization Verification ⚠️ (LOW PRIORITY)

**Status:** Basic implementation exists, needs verification

**Tasks:**

- [ ] Verify `inviteLease()` in `leaseService.ts` properly links to approved
      lease
- [ ] Ensure tenant access rights are set up after approval
- [ ] Validate payment schedules are created on approval
- [ ] Test data integrity after approval workflow
- [ ] Verify lease status transitions correctly (draft → active)

---

## Issues Discovered During Development

### 1. Missing Notification Integration

**Issue:** API endpoints for approve/reject don't send notifications **Impact:**
Landlords and tenants won't receive email/dashboard notifications **Fix
Required:** Implement notification service and integrate with endpoints

### 2. Dashboard Missing Pending Approvals Section

**Issue:** Landlord dashboard doesn't show pending lease approvals **Impact:**
Landlords must navigate to a separate page to see approvals **Fix Required:**
Add pending approvals section to dashboard

### 3. No Dedicated Approvals Page

**Issue:** `/landlord/approvals` route doesn't exist **Impact:** No centralized
location for landlords to manage approvals **Fix Required:** Create dedicated
approvals page

### 4. Incomplete E2E Test Coverage

**Issue:** No E2E tests for the complete approval workflow **Impact:** Difficult
to verify end-to-end functionality **Fix Required:** Add comprehensive E2E tests

### 5. Variable Naming Consistency

**Issue:** Potential naming inconsistencies between services **Impact:** May
cause confusion during maintenance **Fix Required:** Review and standardize
variable names across files

---

## Verification Steps

After completing each component, run:

```bash
deno check <modified_ts_file>
deno fmt <modified_ts_file>
deno lint <modified_ts_file>
```

**Note:** `deno check` only works on TypeScript files (.ts), not Markdown files
(.md).

---

## Workflow Summary

1. Tenant clicks "Start Lease" → Creates lease with
   `approval_status: 'pending_approval'`
2. Landlord receives notification → Dashboard shows pending approval
3. Landlord reviews and approves/rejects → Updates lease status
4. System finalizes lease → Links records, sets up payments, grants access

---

## Files to Create

- `services/notificationService.ts` - New notification service
- `routes/landlord/approvals/index.tsx` - Dedicated approvals page
- `tests/e2e/lease-approval.spec.ts` - E2E tests for approval workflow

## Files to Modify

- `routes/landlord/dashboard/index.tsx` - Add pending approvals section
- `routes/api/lease/approve.ts` - Add notification call
- `routes/api/lease/reject.ts` - Add notification call
- `routes/api/lease/request-approval.ts` - Add notification call
- `services/e2eFixtures.ts` - Add notification E2E fixtures

---

## Success Criteria

- [ ] All lease activations require landlord approval
- [ ] Tenants see clear approval status
- [ ] Landlords can easily review and approve/reject
- [ ] Notifications are sent reliably
- [ ] Lease finalization works correctly
- [ ] All tests pass
- [ ] Dashboard shows pending approvals
- [ ] Dedicated approvals page exists