Add Block system research findings summary
Complete analysis of Block 122 (Tuffy Appointment Form) including:
- Architecture analysis of 43KB enterprise-grade form
- 4-phase deprecation migration strategy
- Technical insights on Block.rb rendering engine
- Data binding and conditional rendering patterns
- Implementation approach with Rails components
- Testing strategy for complex form migration
- Effort estimation (3-4 weeks per block)
This research complements the detailed case study and provides
a comprehensive foundation for Block deprecation project.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bob Roberts
parent
07afb1b7ba
commit
6616847612
1 changed files with 239 additions and 0 deletions
239
BLOCK_SYSTEM_RESEARCH_FINDINGS.md
Normal file
239
BLOCK_SYSTEM_RESEARCH_FINDINGS.md
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
# PISTN Block System Research - Complete Analysis
|
||||
|
||||
**Date**: 2025-10-24
|
||||
**Status**: Comprehensive production analysis completed
|
||||
|
||||
---
|
||||
|
||||
## What Are Blocks?
|
||||
|
||||
Blocks are PISTN's custom templating engine that allows CSRs (Customer Service Representatives) to create dealer-specific HTML/CSS/JavaScript without code changes. They use a hierarchical structure with `{{variable}}` handlebars-style syntax.
|
||||
|
||||
## Key Findings from Production Analysis
|
||||
|
||||
### Block 122: Tuffy Appointment Form
|
||||
- **Size**: 43KB (~1,150 lines)
|
||||
- **Complexity**: Enterprise-grade form with 4-step wizard
|
||||
- **Features**:
|
||||
- Multi-step form with client-side state management
|
||||
- Inline JavaScript (600+ lines)
|
||||
- jQuery UI Datepicker integration
|
||||
- Phone verification modal workflow
|
||||
- Existing vehicle lookup and selection
|
||||
- Google Tag Manager event tracking
|
||||
- 12+ conditional renders based on account settings
|
||||
- AJAX calls to fetch time slots
|
||||
|
||||
### Block Whitelist Security Model
|
||||
- Massive whitelist of allowed methods (100+ entries) in Block.rb lines 54-137
|
||||
- Examples: `account.name`, `account.online_scheduling_promo_message`, `account.use_mobile_verification`
|
||||
- Security by whitelist is manageable but requires constant review
|
||||
|
||||
### Database Schema
|
||||
```
|
||||
blocks table:
|
||||
- id, parent_id (hierarchical tree)
|
||||
- role (semantic: "header", "content", "footer", etc.)
|
||||
- tag (type classification)
|
||||
- content (HTML + Handlebars template)
|
||||
- account_id (NULL = universal, specific = account-only)
|
||||
- position (float for ordering)
|
||||
- attrs_data (JSON config)
|
||||
- editable, wysiwyg, library flags
|
||||
```
|
||||
|
||||
## Why Block 122 Matters
|
||||
|
||||
Block 122 represents the **maximum complexity** in PISTN's Block system:
|
||||
- Multi-step form wizard
|
||||
- Complex JavaScript behavior
|
||||
- Account-specific customizations
|
||||
- Feature flags (phone verification, towing, address fields, costco membership)
|
||||
- State management across 4 steps
|
||||
- Form field synchronization to confirmation display
|
||||
|
||||
**If Block 122 can be successfully migrated to Rails views, ANY block can be migrated.**
|
||||
|
||||
## Migration Strategy Summary
|
||||
|
||||
### High-Level Approach
|
||||
1. **Decompose** the monolithic Block into Rails components
|
||||
- View partials for each form step
|
||||
- Presenter for data preparation
|
||||
- Service classes for validation
|
||||
- Stimulus controller for JavaScript
|
||||
|
||||
2. **Modernize** from inline JavaScript to standard Rails patterns
|
||||
- Extract 600+ lines to external Stimulus controller
|
||||
- Replace jQuery with standard fetch API
|
||||
- Use Rails form helpers instead of raw HTML
|
||||
|
||||
3. **Enhance** with Rails conventions
|
||||
- Active Record validations
|
||||
- Authorization policies
|
||||
- Test coverage (unit + integration + E2E)
|
||||
|
||||
### 4-Phase Deprecation Plan
|
||||
1. **Analysis** (in progress): Map all blocks, categorize by complexity ✅
|
||||
2. **Create Views**: Build Rails replacements (8 weeks per block)
|
||||
3. **Gradual Migration**: Feature flags, per-account rollout
|
||||
4. **Decommission**: Remove Block system, clean up database
|
||||
|
||||
## Key Technical Insights
|
||||
|
||||
### Block.rb Rendering Engine (1014 lines)
|
||||
- `render(opts)`: Main orchestrator (lines 300-426)
|
||||
- `subbed_content(opts)`: Template substitution engine for {{}} syntax (lines 436-599)
|
||||
- `eval_bool(str, opts)`: Evaluate boolean expressions (lines 642-678)
|
||||
- `eval_str(str, opts)`: Evaluate string expressions with dot notation (lines 680-752)
|
||||
|
||||
### Account-Specific Inheritance
|
||||
- Blocks can be universal (account_id = NULL)
|
||||
- Or account-specific (account_id = specific account)
|
||||
- Inheritance: Account-specific > Group > Universal
|
||||
- Caching layer adds complexity and potential for cache invalidation bugs
|
||||
|
||||
### Pain Points Identified
|
||||
1. **Developer Experience**: 1000+ lines of state machine rendering logic
|
||||
2. **Maintenance**: Complex caching, N+1 query potential, hard to test
|
||||
3. **Performance**: Interpretation layer overhead
|
||||
4. **CSR UX**: Admin UI is clunky, no real-time preview
|
||||
5. **Architecture**: Views required anyway (blocks are extra layer)
|
||||
|
||||
## What We Now Know About Block 122
|
||||
|
||||
### HTML Structure
|
||||
- 4-step wizard form with Bootstrap classes
|
||||
- Multi-column layout (8-col form + 4-col sidebar)
|
||||
- Modal for phone verification
|
||||
- Loading overlay for time slot fetching
|
||||
- Responsive (mobile-first approach with d-none/d-lg-block)
|
||||
|
||||
### JavaScript Requirements
|
||||
- Step navigation with validation
|
||||
- Date picker with availability filtering
|
||||
- Form field → confirmation display binding
|
||||
- Phone verification with code entry
|
||||
- Existing vehicle selection with lookup
|
||||
- Service category loop with checkboxes
|
||||
- Store hours validation
|
||||
- Required field validation
|
||||
|
||||
### Conditional Rendering
|
||||
- `account.use_mobile_verification` → Show phone verification section
|
||||
- `account.show_towing` → Show towing field
|
||||
- `account.require_addr_for_appt` → Show address fields
|
||||
- `account.require_costco_membership_number` → Show costco membership field
|
||||
- `account.render_new_appt_times_string` → Filter calendar or show time dropdown
|
||||
|
||||
### Data Bindings
|
||||
- Form fields sync to confirmation display on change
|
||||
- Service selections update confirmation service list
|
||||
- Vehicle selection updates vehicle display
|
||||
- Date/time selections update confirmation
|
||||
- Customer name, email, phone update throughout
|
||||
|
||||
## Implementation Insights
|
||||
|
||||
### Presenter Class Benefits
|
||||
```ruby
|
||||
class AppointmentFormPresenter
|
||||
# Replaces whitelist logic
|
||||
def show_financing_section?; end
|
||||
def use_mobile_verification?; end
|
||||
def require_address?; end
|
||||
# Clear, testable business logic
|
||||
end
|
||||
```
|
||||
|
||||
### Service Layer Pattern
|
||||
```ruby
|
||||
class ValidateAppointmentService
|
||||
def perform(account, step, data)
|
||||
# Complex validation logic
|
||||
# Returns { valid: true/false, errors: [...] }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### View Decomposition
|
||||
Instead of 1,150-line monolithic block:
|
||||
- 120-line main form wrapper
|
||||
- 80-line step 1 (services)
|
||||
- 90-line step 2 (date/time)
|
||||
- 110-line step 3 (customer info)
|
||||
- 100-line step 4 (confirmation)
|
||||
- 60-line modal (phone verification)
|
||||
- Much more readable and testable
|
||||
|
||||
## Testing Strategy for Block 122
|
||||
|
||||
### Unit Tests (Service Layer)
|
||||
- Validation logic for each step
|
||||
- Date validation rules
|
||||
- Store hours checks
|
||||
- Phone verification flow
|
||||
- Vehicle selection logic
|
||||
|
||||
### View Tests (Presenter + Partial)
|
||||
- Conditional sections render correctly
|
||||
- Form fields present
|
||||
- Confirmation displays correct data
|
||||
- Error messages display
|
||||
|
||||
### Integration Tests (Controller)
|
||||
- Multi-step form flow
|
||||
- AJAX calls (time slots, phone verify)
|
||||
- Form submission success
|
||||
- Database state after creation
|
||||
|
||||
### E2E Tests (Capybara)
|
||||
- Complete user flow through all 4 steps
|
||||
- Phone verification workflow
|
||||
- Existing vehicle selection
|
||||
- Error scenarios and retries
|
||||
- Cross-browser compatibility
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
- **Presenter + Controller**: 2 days
|
||||
- **View Partials**: 3 days
|
||||
- **JavaScript Extraction & Validation**: 5 days
|
||||
- **Service Classes**: 3 days
|
||||
- **Testing**: 5 days
|
||||
- **Bug Fixes & Polish**: 2 days
|
||||
|
||||
**Total**: ~3-4 weeks for one block (block 122)
|
||||
**With learnings applied to subsequent blocks**: 1 week per block
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Complete architectural analysis (done)
|
||||
2. Create feature flag infrastructure in Rails
|
||||
3. Build Presenter class for Block 122
|
||||
4. Create view partials with code examples
|
||||
5. Extract JavaScript to Stimulus controller
|
||||
6. Build validation services
|
||||
7. Create test suite (unit + integration + E2E)
|
||||
8. Deploy to test account with feature flag
|
||||
9. Beta test and iterate
|
||||
10. Gradual rollout to all accounts
|
||||
|
||||
## Key Takeaway
|
||||
|
||||
**Block 122 is not just a form - it's a complete SPA (Single Page Application) embedded in the Block system.**
|
||||
|
||||
Migrating it to Rails views means:
|
||||
- Taking the logic out of the Block interpreter
|
||||
- Using proper Rails patterns (presenters, services, partials)
|
||||
- Making it testable and maintainable
|
||||
- Enabling future enhancements
|
||||
|
||||
The migration is complex but **entirely feasible** and will result in cleaner, more maintainable code.
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `BLOCKS_DEPRECATION_STRATEGY.md` - 4-phase migration plan
|
||||
- `BLOCK_CASE_STUDY_TUFFY_APPOINTMENT_FORM.md` - Complete Block 122 analysis with code
|
||||
Loading…
Add table
Reference in a new issue