init projectmycelium

2025-09-01 21:37:01 -04:00
commit b41efb0e99
319 changed files with 128160 additions and 0 deletions
--- a/docs/dev/design/archive/credits_refactor_completion_plan.md
+++ b/docs/dev/design/archive/credits_refactor_completion_plan.md
@@ -0,0 +1,234 @@
+# USD Credits Refactor Completion Plan
+
+## Executive Summary
+
+The USD Credits system refactor is **75% complete** with major infrastructure in place, but **298 TFP references remain** in frontend templates and **169 in backend code**. This plan prioritizes user-facing fixes first, then backend consistency, followed by complete cleanup.
+
+## Current State Analysis
+
+### ✅ **Completed Successfully**
+- Auto-topup system (service, API endpoints, routes)
+- Buy Now functionality with auto-topup integration  
+- Core currency service updated to USD default
+- Main wallet UI updated to "USD Credits Wallet"
+- TFP documentation converted to USD Credits documentation
+
+### ❌ **Critical Issues Remaining**
+
+#### Frontend Issues (298 TFP references)
+- Dashboard wallet still shows "Buy TFP" buttons
+- All marketplace pages show "Min Price (TFP)" filters
+- Documentation overview still mentions "TFP system"
+- Getting started guide references "TFP Wallet"
+- Transaction displays show TFP amounts
+- Charts titled "TFP Usage Trend"
+
+#### Backend Issues (169 TFP references)
+- API routes: `/wallet/buy-tfp`, `/wallet/sell-tfp`
+- Transaction types: `TFPPurchase`, `TFPSale`
+- Service methods: `convert_tfp_to_display_currency`
+- Mock data hardcoded to TFP pricing
+- Currency calculations assume TFP base
+
+## Implementation Plan
+
+### **PHASE 1: Critical User-Facing Fixes (Week 1)**
+
+**Priority: IMMEDIATE - Fixes user confusion**
+
+#### 1.1 Dashboard Wallet Page
+**File**: `projectmycelium/src/views/dashboard/wallet.html`
+**Changes**:
+- Line 5: Change "TFP Wallet" → "Credits Wallet"
+- Line 53-54: Change "Buy TFP" → "Buy Credits"
+- Line 56-57: Change "Transfer TFP" → "Transfer Credits"
+- Lines 217-252: Update modal titles and content
+- All transaction displays: Remove "TFP" suffix
+
+#### 1.2 Marketplace Price Filters
+**Files**: All marketplace templates
+**Changes**:
+- `marketplace/gateways.html` lines 42, 47: "Min/Max Price (TFP)" → "Min/Max Price ($)"
+- `marketplace/services.html` lines 53, 58: Same changes
+- `marketplace/applications.html` lines 52, 57: Same changes
+- `marketplace/three_nodes.html` lines 56, 61: Same changes
+- `marketplace/compute_resources.html` lines 82: "Price Range (TFP)" → "Price Range ($)"
+
+#### 1.3 Documentation Overview
+**File**: `projectmycelium/src/views/docs/index.html`
+**Changes**:
+- Line 25: "TFP system" → "USD credits system"
+- Line 45: "TFP transferred" → "Credits transferred"
+- Lines 141-143: "Setup TFP Wallet" → "Setup Credits Wallet"
+- All table entries: Replace TFP references
+
+#### 1.4 Getting Started Guide
+**File**: `projectmycelium/src/views/docs/getting_started.html`
+**Changes**:
+- Line 36: "Setup Your TFP Wallet" → "Setup Your Credits Wallet"
+- Line 40: "ThreeFold Points (TFP)" → "USD Credits"
+- Line 43: "TFP wallet" → "Credits wallet"
+- Line 45: "Add TFP" → "Add Credits"
+
+### **PHASE 2: Backend API Migration (Week 2)**
+
+**Priority: HIGH - Ensures API consistency**
+
+#### 2.1 Add New Credits API Endpoints
+**File**: `projectmycelium/src/routes/mod.rs`
+**Changes**:
+```rust
+// Add new credits endpoints
+.route("/wallet/buy-credits", web::post().to(WalletController::buy_credits))
+.route("/wallet/sell-credits", web::post().to(WalletController::sell_credits))
+.route("/wallet/transfer-credits", web::post().to(WalletController::transfer_credits))
+
+// Keep old endpoints for compatibility
+.route("/wallet/buy-tfp", web::post().to(WalletController::buy_tfp)) // Deprecated
+```
+
+#### 2.2 Update Transaction Types
+**File**: `projectmycelium/src/models/user.rs`
+**Changes**:
+```rust
+// Add new transaction types
+CreditsPurchase { payment_method: String },
+CreditsSale { currency: String, exchange_rate: Decimal },
+CreditsTransfer { to_user: String, note: Option<String> },
+
+// Keep old types for data migration
+#[deprecated]
+TFPPurchase { payment_method: String },
+```
+
+#### 2.3 Update Currency Service Methods
+**File**: `projectmycelium/src/services/currency.rs`
+**Changes**:
+```rust
+// Rename methods
+pub fn convert_credits_to_display_currency(...) // was convert_tfp_to_display_currency
+pub fn convert_display_currency_to_credits(...) // was convert_display_currency_to_tfp
+```
+
+#### 2.4 Update Controller Methods
+**File**: `projectmycelium/src/controllers/wallet.rs`
+**Changes**:
+- Add `buy_credits()`, `sell_credits()`, `transfer_credits()` methods
+- Update request/response structs to use "credits" terminology
+- Maintain backward compatibility with existing TFP endpoints
+
+### **PHASE 3: Complete Cleanup (Week 3)**
+
+**Priority: MEDIUM - Removes all remaining inconsistencies**
+
+#### 3.1 All Documentation Files
+**Files**: All `projectmycelium/src/views/docs/*.html`
+**Changes**:
+- Replace all "TFP" references with "Credits" or "USD Credits"
+- Update pricing examples to show dollar amounts
+- Fix all navigation links and references
+
+#### 3.2 Legal Documents
+**Files**: `projectmycelium/src/views/legal/*.html`
+**Changes**:
+- Update terms to reference "USD Credits" instead of TFP
+- Maintain legal accuracy while updating terminology
+- Update exchange rate references
+
+#### 3.3 Dashboard and Statistics
+**Files**: All dashboard templates
+**Changes**:
+- Chart titles: "TFP Usage" → "Credits Usage"
+- Earnings displays: "TFP/month" → "$/month"
+- Balance displays: Remove "TFP" suffixes
+- Staking interfaces: Update to credits terminology
+
+#### 3.4 Mock Data and Services
+**Files**: `projectmycelium/src/services/mock_data.rs`, pricing services
+**Changes**:
+- Update hardcoded currency references
+- Change default pricing to USD
+- Update service pricing calculations
+
+## Testing Strategy
+
+### **Phase 1 Testing**
+- [ ] User registration and wallet setup flow
+- [ ] Marketplace browsing and price display
+- [ ] Documentation navigation and clarity
+- [ ] New user onboarding experience
+
+### **Phase 2 Testing**
+- [ ] API endpoint functionality (both old and new)
+- [ ] Transaction creation and display
+- [ ] Currency conversion accuracy
+- [ ] Backward compatibility with existing data
+
+### **Phase 3 Testing**
+- [ ] Complete user journey from signup to purchase
+- [ ] All documentation links and references
+- [ ] Legal document accuracy
+- [ ] Performance impact of changes
+
+## Risk Mitigation
+
+### **High Risk: User Confusion**
+- **Mitigation**: Implement Phase 1 fixes immediately
+- **Monitoring**: Track support tickets for TFP/Credits confusion
+- **Rollback**: Maintain ability to revert terminology changes
+
+### **Medium Risk: API Breaking Changes**
+- **Mitigation**: Maintain old endpoints during transition
+- **Versioning**: Add API version headers for new endpoints
+- **Documentation**: Clear migration guide for API consumers
+
+### **Low Risk: Data Migration**
+- **Mitigation**: Gradual migration of transaction types
+- **Backup**: Full database backup before changes
+- **Validation**: Automated tests for data integrity
+
+## Success Metrics
+
+### **Phase 1 Success**
+- Zero TFP references in user-facing wallet interface
+- All marketplace prices display in USD format
+- Documentation consistently uses "Credits" terminology
+- User onboarding flow mentions only Credits
+
+### **Phase 2 Success**
+- New Credits API endpoints functional
+- Old TFP endpoints marked deprecated but working
+- All new transactions use Credits types
+- Currency service methods renamed
+
+### **Phase 3 Success**
+- Zero TFP references in entire codebase
+- All documentation updated and consistent
+- Legal documents accurate and current
+- Performance maintained or improved
+
+## Timeline
+
+### **Week 1: User-Facing Fixes**
+- Day 1-2: Dashboard wallet updates
+- Day 3-4: Marketplace price filters
+- Day 5-6: Documentation overview and getting started
+- Day 7: Testing and refinement
+
+### **Week 2: Backend Migration**
+- Day 8-9: New API endpoints
+- Day 10-11: Transaction type updates
+- Day 12-13: Currency service refactoring
+- Day 14: Integration testing
+
+### **Week 3: Complete Cleanup**
+- Day 15-17: All documentation updates
+- Day 18-19: Legal document updates
+- Day 20-21: Dashboard and statistics cleanup
+- Day 22: Final testing and deployment
+
+## Conclusion
+
+This plan addresses the most critical user-facing issues first while maintaining system stability. The phased approach allows for testing and validation at each stage, reducing risk while ensuring a complete transition to the USD Credits system.
+
+The refactor is substantial but manageable, with clear priorities and measurable success criteria. Once complete, users will have a consistent, intuitive experience with clear USD pricing throughout the platform.