BillTracker/FUTURE.md

Bill Tracker — Future Improvements

This document tracks potential future enhancements for Bill Tracker.

Last Updated: 2026-05-10
Current Version: v0.24.2

How to Use This Document

This file is a living document. Agents should:

1. Read this file before proposing changes
2. Add new recommendations with priority levels
3. Never add completed items — move those to HISTORY.md instead
4. Reference this file when dispatching improvement tasks
5. Only Ripley can remove items from this list.

Priority Format

All items must include the priority emoji in their heading, matching the section they belong to:

Priority	Emoji	Heading Format
CRITICAL	🔴	### 🔴 Title — CRITICAL
HIGH	🟠	### 🟠 Title — HIGH
MEDIUM	🟡	### 🟡 Title — MEDIUM
LOW	🔵	### 🔵 Title — LOW
NICE TO HAVE	💭	### 💭 Title — NICE TO HAVE

Items are grouped under their priority section heading (## 🔴 CRITICAL, ## 🟠 HIGH, etc.) and sorted most-impactful-first within each tier.

Pending Recommendations

🔴 CRITICAL

🔴 Notification Runner Leaks Bill Details Across Users — CRITICAL ✅ FIXED (v0.23.2)

Moved to HISTORY.md

🟠 HIGH

🟠 Admin Can Toggle Payments on Any User Bill — HIGH ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟠 Analytics Validation Errors Crash Instead of Returning 400 — HIGH ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟠 User Export Drops Recurrence and History-Range Data — HIGH ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟠 Single-User Mode Can Lock Itself Out When Expired Sessions Exist — HIGH ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 MEDIUM

🟡 Password Change Rate Limiter Applies to Every Profile Endpoint — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 Profile Password Change Does Not Invalidate Other Sessions — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 CSRF Defaults Conflict with SPA Token Loading — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 Change-Password Routes Are Globally Exempted from CSRF — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 Notification Due-Day Math Can Miss Same-Day Reminders — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

🟡 Upcoming Bills Allows Negative Day Windows — MEDIUM ✅ FIXED (v0.24.0)

Moved to HISTORY.md

Architecture: Business Logic Mixed with Route Handlers

Priority: MEDIUM
Added: 2026-05-08 by Neo

Description: Many routes contain business logic that should be extracted to service layers.

Rationale:

• bills.js contains parseDueDay(), parseInterestRate() — validation logic
• tracker.js contains date/range calculations that are reused across routes
• admin.js has complex OIDC config building mixed with routing
• analytics.js has complex date-building logic (buildMonths, monthKey, etc.)

Implementation Notes:

• Files to modify: Multiple route files + new service files in /services/
• Estimated effort: 8 hours
• Proposed structure:

  /services/billsService.js
  /services/trackerService.js
  /services/analyticsService.js
  /services/authService.js (existing)
  /services/oidcService.js (existing)
  /services/cleanupService.js (existing)
  

• Route handlers should call services, not contain business logic

Skip First-Login User Creation When ENV Seeds Users ✅ COMPLETED (v0.22.3)

Moved to HISTORY.md

No Rollback Capability for Failed Migrations ✅ COMPLETED (v0.23.1)

Moved to HISTORY.md

Limited Error Handling and Logging for Migrations ✅ COMPLETED (v0.23.0)

Moved to HISTORY.md

Rationale:

• Migration errors are silent or unclear
• No logging of which migration failed or why
• No way to diagnose schema inconsistencies
• Risk: slow debugging on production issues

Implementation Notes:

• Add detailed logging: [migration] Applying v0.20.0: Add user_groups table
• Include timing: [migration] v0.20.0 completed in 234ms
• Log precondition checks: [migration] Checking: table_exists('users')
• Error log with context: [migration-error] v0.20.0 failed: UNIQUE constraint failed on users.username

---

🔵 LOW

🔵 Export Formats Include Sensitive Bill Credential Fields by Default — LOW ✅ FIXED (v0.24.1)

Moved to HISTORY.md

🔵 Duplicate Local Login Route Increases Auth Drift Risk — LOW ✅ FIXED (v0.23.2)

Moved to HISTORY.md

Add comprehensive unit and integration tests

Priority: LOW
Added: 2026-05-08 by Scarlett

Description: Currently no unit tests exist for components or hooks. The only testing appears to be functional tests in test-functional.js. Component-level testing is missing.

Rationale: Code quality and maintainability. Unit tests catch regressions and document component behavior. Bill Tracker has complex business logic (bill calculations, monthly state, analytics) that should be tested.

Implementation Notes:

• Set up Jest + React Testing Library
• Test key components: BillModal, TrackerPage row, BillsTableInner
• Test hooks: useAuth, custom form hooks
• Test utility functions in client/lib/utils.js
• Consider vitest for faster test execution
• Add CI integration for test execution
• Files likely to be modified: Add client/test/ directory, add jest.config.cjs
• Estimated effort: 8-12 hours for baseline coverage

Features: Missing Export for User-Specific Reports

Priority: LOW
Added: 2026-05-08 by Neo

Description: No built-in way to export filtered data (e.g., "all bills in category X for last 6 months").

Rationale:

• /api/analytics/summary exists but returns JSON only
• Users cannot generate Excel/PDF reports
• No programmatic way to get export links for specific filters
• /api/export/user-excel exports everything, not filtered views

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/routes/export.js
• Estimated effort: 6 hours
• Add endpoints:
  • GET /api/export/user-excel?category_id=1&start=2026-01&end=2026-06
  • GET /api/export/user-json?filter=bills&status=missed
  • Add report title/description to export metadata

Features: Missing Bill Grouping and Reorganization API

Priority: LOW
Added: 2026-05-08 by Neo

Description: No way to reorder bills, drag-and-drop, or group by custom criteria.

Rationale:

• bills table has due_day ordering but no manual sort order
• Frontend likely orders by due_day only
• Users cannot create bill groups or categories for bills
• No way to mark bills as "hidden" or "archived" without deactivating

Implementation Notes:

• Files to modify: /home/kaspa/.openclaw/Projects/bill-tracker/db/schema.sql, /routes/bills.js
• Estimated effort: 6 hours
• Add:
  • sort_order column to bills table (default NULL, ordered first by sort_order then due_day)
  • PUT /api/bills/reorder endpoint accepting {bill_id: new_index}
  • PUT /api/bills/:id/archived to soft-dearchive (sets archived flag)

---

💭 NICE TO HAVE

Add consistent form state management pattern

Priority: MEH
Added: 2026-05-08 by Scarlett

Description: Form state management is inconsistent across components. Some use useState for each field, others use form libraries. Validation patterns vary.

Rationale: Consistency and maintainability. A consistent pattern makes it easier to add new forms and reduce bugs.

Implementation Notes:

• Consider react-hook-form for complex forms
• Create reusable form field components (InputField, SelectField, etc.)
• Standardize validation approach
• Files likely to be modified: client/components/*.jsx
• Estimated effort: 4-6 hours for migration

---

Template for New Recommendations

### [Feature Name]
**Priority:** CRITICAL / HIGH / MEDIUM / LOW / MEH  
**Added:** YYYY-MM-DD by [Agent]

**Description:**
Brief description of the improvement.

**Rationale:**
Why this matters.

**Implementation Notes:**
- Technical approach
- Files likely to be modified
- Estimated effort

**Depends On:**
Any prerequisites or blocking issues.

Completed Items

✅ Security: Rate Limiting on /api/about-admin — MEDIUM

Completed: 2026-05-09 (v0.19.0) Fix: adminActionLimiter (30 req/15min) applied to /api/about-admin route.

✅ Security: Markdown Sanitization in AboutPage — MEDIUM

Completed: 2026-05-09 (v0.19.0) Fix: rehype-sanitize added to AboutPage.jsx ReactMarkdown component.

✅ Security: aboutAdmin() in API Client — LOW

Completed: 2026-05-09 (v0.19.0) Fix: aboutAdmin endpoint function added to client/api.js.

---