# TODO - Lease Approval Workflow

## Completed Components

### 1. Database Schema ✅

- [x] Added approval workflow fields to `leases` table:
  - `approval_status` TEXT DEFAULT 'pending_approval'
  - `approval_requested_at` BIGINT
  - `approved_at` BIGINT
  - `approved_by` TEXT REFERENCES users(id)
  - `rejection_reason` TEXT
- [x] Created migration SQL file: `drizzle/0008_add_lease_approval_fields.sql`
- [x] Updated database interfaces in `db/schema.ts`

### 2. API Endpoints ✅

- [x] Created `POST /api/lease/request-approval` - Tenant initiates lease
- [x] Created `POST /api/lease/approve` - Landlord approval
- [x] Created `POST /api/lease/reject` - Landlord rejection
- [x] Created `GET /api/lease/pending-approvals` - Landlord dashboard
- [x] Extended `leaseService.ts` with approval functions:
  - `requestLeaseApproval()`
  - `approveLease()`
  - `rejectLease()`
  - `getPendingApprovals()`

### 3. Tenant Invitation Page ✅

- [x] Updated `/tenant/invite/[invite_id].tsx` to check lease status
- [x] Added status-based UI states:
  - No lease: "Start Lease" button
  - Pending: "Pending Landlord Approval"
  - Approved: "Lease Approved - Continue"
  - Rejected: "Lease Rejected" with contact info
- [x] Added progress indicator showing approval steps
- [x] Updated POST handler to call approval API

### 4. Landlord Service ✅

- [x] Added `getPendingLeaseApprovals()` function in `landlordService.ts`

---

## Incomplete / Needs Work

### 1. Notification Service ❌ (HIGH PRIORITY)

**Status:** File does not exist

**Tasks:**

- [ ] Create `services/notificationService.ts` for centralized notifications
- [ ] Implement `sendLeaseApprovalRequest()` function
- [ ] Implement `sendLeaseApproved()` function
- [ ] Implement `sendLeaseRejected()` function
- [ ] Integrate with user `notification_preferences_json` system
- [ ] Follow `messageService.ts` pattern for E2E fixture support
- [ ] Add E2E fixture functions in `services/e2eFixtures.ts`

**Integration Points:**

- Call `sendLeaseApprovalRequest()` in `routes/api/lease/request-approval.ts`
- Call `sendLeaseApproved()` in `routes/api/lease/approve.ts`
- Call `sendLeaseRejected()` in `routes/api/lease/reject.ts`

### 2. Landlord Dashboard Updates ⚠️ (HIGH PRIORITY)

**Status:** Dashboard exists but missing "Pending Lease Approvals" section

**Current State:**

- Dashboard has "Pending Applications" section (for tenant applications)
- Dashboard does NOT have "Pending Lease Approvals" section
- `getPendingLeaseApprovals()` function exists in `landlordService.ts` but is
  not used

**Tasks:**

- [ ] Add "Pending Lease Approvals" section to
      `routes/landlord/dashboard/index.tsx`
- [ ] Call `getPendingLeaseApprovals()` from `landlordService.ts`
- [ ] Display approval cards with property/tenant details
- [ ] Include approve/reject buttons calling `/api/lease/approve` and
      `/api/lease/reject`
- [ ] Use existing card styling pattern from dashboard
- [ ] Add navigation badge for pending approvals count

### 3. Dedicated Approvals Page ❌ (MEDIUM PRIORITY)

**Status:** Page does not exist

**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