Integrate MLS listings with property map and add smart sync
Property Map: - Replace ACF-based property display with MLS database queries - Use real lat/lng coordinates from MLS (100% coverage) - Create property-card-mls.php template for MLS property cards - Update AJAX handler to filter MLS properties MLS Plugin Enhancements: - Add 'wp mls run' smart sync command (auto-detects full/incremental/resume) - Add database index migrations for lat/lng and composite search indexes - Add comprehensive README.md documentation Documentation: - Update site README.md with sysadmin quick reference - Add FEATURES_PENDING_12_15.md tracking client feature requests 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Hanson.xyz Dev
@@ -1,33 +1,228 @@
|
||||
# HomeProz Real Estate WordPress Site
|
||||
|
||||
Custom WordPress theme for HomeProz Real Estate (Albert Lea, MN).
|
||||
Custom WordPress site for HomeProz Real Estate (Albert Lea, MN) with MLS Grid integration.
|
||||
|
||||
**Production URL:** https://homeprozrealestate.com
|
||||
|
||||
## Quick Reference for Sysadmins
|
||||
|
||||
### Required Cron Job
|
||||
|
||||
Add to system crontab (`crontab -e`):
|
||||
|
||||
```bash
|
||||
# MLS property sync - runs every 15 minutes
|
||||
*/15 * * * * cd /var/www/html && wp mls run --silent --allow-root >> /var/log/mls-sync.log 2>&1
|
||||
```
|
||||
|
||||
This single cron job handles everything:
|
||||
- Initial full sync on first run (~30K properties, takes 30-45 min)
|
||||
- Incremental updates on subsequent runs
|
||||
- Automatic recovery from failures
|
||||
- Safe concurrent execution (aborts if already running)
|
||||
|
||||
### Manual Sync Commands
|
||||
|
||||
```bash
|
||||
# Check sync status
|
||||
wp --allow-root mls status
|
||||
|
||||
# Run sync manually
|
||||
wp --allow-root mls run
|
||||
|
||||
# View database statistics
|
||||
wp --allow-root mls stats
|
||||
|
||||
# Test API connection
|
||||
wp --allow-root mls test connection
|
||||
```
|
||||
|
||||
### Log Files
|
||||
|
||||
| Log | Location | Purpose |
|
||||
|-----|----------|---------|
|
||||
| MLS Sync | `/var/log/mls-sync.log` | Cron sync output |
|
||||
| WordPress | `/var/www/html/wp-content/debug.log` | PHP errors (if WP_DEBUG) |
|
||||
| Missing Media | `/var/www/html/wp-content/uploads/mls-missing-media.log` | Failed image downloads |
|
||||
|
||||
### API Credentials
|
||||
|
||||
MLS Grid credentials are in `wp-config.php`:
|
||||
|
||||
```php
|
||||
define('MLSGRID_ACCESS_TOKEN', '...');
|
||||
```
|
||||
|
||||
Contact MLS Grid support (support@mlsgrid.com) for token issues.
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `/wp-content/themes/homeproz/` - Custom theme
|
||||
- `/db-snapshots/` - Database snapshots for each development phase
|
||||
- `/contract/` - Project documentation and planning
|
||||
- `/CLAUDE.md` - Development mandates and specifications
|
||||
```
|
||||
/var/www/html/
|
||||
├── wp-config.php # WordPress + MLS Grid config
|
||||
├── wp-content/
|
||||
│ ├── themes/homeproz/ # Custom theme
|
||||
│ ├── plugins/
|
||||
│ │ └── mls-by-hansonxyz/ # MLS sync plugin
|
||||
│ └── uploads/
|
||||
│ └── mls-listings/ # Cached property images
|
||||
├── db-snapshots/ # Database snapshots
|
||||
├── contract/ # Project documentation
|
||||
├── CLAUDE.md # AI development context
|
||||
└── DEPENDENCIES.md # System dependencies
|
||||
```
|
||||
|
||||
## Development
|
||||
## Key Components
|
||||
|
||||
### Custom Theme: HomeProz
|
||||
|
||||
Location: `/wp-content/themes/homeproz/`
|
||||
|
||||
Dark/rust brand aesthetic with ACF-powered property listings.
|
||||
|
||||
```bash
|
||||
# Build theme assets
|
||||
cd wp-content/themes/homeproz
|
||||
npm install
|
||||
npm run dev # Development with hot reload
|
||||
npm run build # Production build
|
||||
npm run build
|
||||
```
|
||||
|
||||
### MLS Plugin: mls-by-hansonxyz
|
||||
|
||||
Location: `/wp-content/plugins/mls-by-hansonxyz/`
|
||||
|
||||
Syncs property data from NorthStar MLS via MLS Grid API.
|
||||
|
||||
See `/wp-content/plugins/mls-by-hansonxyz/README.md` for full documentation.
|
||||
|
||||
### Custom Post Types
|
||||
|
||||
| Post Type | URL | Description |
|
||||
|-----------|-----|-------------|
|
||||
| Property | `/properties/` | MLS listings (ACF fields) |
|
||||
| Agent | `/agents/` | Team member profiles |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- WordPress 6.x
|
||||
- PHP 8.1+
|
||||
- Tailwind CSS
|
||||
- SCSS (via Vite)
|
||||
- MySQL 8.0
|
||||
- Tailwind CSS + SCSS (via Vite)
|
||||
- jQuery
|
||||
- ACF Pro
|
||||
- WP-CLI
|
||||
|
||||
## Client
|
||||
## Development Commands
|
||||
|
||||
HomeProz Real Estate, LLC
|
||||
111 E Clark St, Albert Lea, MN 56007
|
||||
```bash
|
||||
# Theme development
|
||||
cd wp-content/themes/homeproz
|
||||
npm install
|
||||
npm run dev # Dev server with hot reload
|
||||
npm run build # Production build
|
||||
|
||||
# Database snapshot (includes timestamp)
|
||||
./dev_commit.sh "commit message"
|
||||
|
||||
# WP-CLI
|
||||
wp --allow-root <command>
|
||||
```
|
||||
|
||||
## MLS Data Flow
|
||||
|
||||
```
|
||||
MLS Grid API (NorthStar MLS)
|
||||
|
|
||||
v
|
||||
wp mls run (cron every 15 min)
|
||||
|
|
||||
v
|
||||
wp_mls_properties table (~30K Active/Pending listings)
|
||||
|
|
||||
v
|
||||
Theme displays via mls_get_properties() API
|
||||
|
|
||||
v
|
||||
Images fetched on-demand from MLS Grid
|
||||
|
|
||||
v
|
||||
Cached in wp-content/uploads/mls-listings/
|
||||
```
|
||||
|
||||
## Maintenance Tasks
|
||||
|
||||
### Daily
|
||||
|
||||
- Cron job runs automatically every 15 minutes
|
||||
- Monitor `/var/log/mls-sync.log` for errors
|
||||
|
||||
### Weekly
|
||||
|
||||
- Check `wp --allow-root mls stats` for data health
|
||||
- Review disk space for cached images
|
||||
|
||||
### Monthly
|
||||
|
||||
- Review MLS Grid rate limit usage: `wp --allow-root mls status rate-limits`
|
||||
- Clear orphaned media: `wp --allow-root mls cache cleanup`
|
||||
|
||||
### After Server Migration
|
||||
|
||||
1. Verify `wp-config.php` has MLS Grid credentials
|
||||
2. Set up cron job (see above)
|
||||
3. Run initial sync: `wp --allow-root mls run`
|
||||
4. Verify: `wp --allow-root mls stats`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No Properties Showing
|
||||
|
||||
```bash
|
||||
# Check if data exists
|
||||
wp --allow-root mls stats
|
||||
|
||||
# Check sync status
|
||||
wp --allow-root mls status
|
||||
|
||||
# Run manual sync
|
||||
wp --allow-root mls run --verbose
|
||||
```
|
||||
|
||||
### Sync Failing
|
||||
|
||||
```bash
|
||||
# Test API connection
|
||||
wp --allow-root mls test connection
|
||||
wp --allow-root mls test auth
|
||||
|
||||
# Check rate limits
|
||||
wp --allow-root mls status rate-limits
|
||||
|
||||
# View resumable syncs
|
||||
wp --allow-root mls recovery list
|
||||
```
|
||||
|
||||
### Images Not Loading
|
||||
|
||||
```bash
|
||||
# Check cache stats
|
||||
wp --allow-root mls media status
|
||||
|
||||
# Check directory permissions
|
||||
ls -la wp-content/uploads/mls-listings/
|
||||
|
||||
# Pre-cache a listing manually
|
||||
wp --allow-root mls media fetch --listing=<key> --limit=10
|
||||
```
|
||||
|
||||
### Clear Everything and Start Fresh
|
||||
|
||||
```bash
|
||||
wp --allow-root mls cache clear --confirm
|
||||
wp --allow-root mls run
|
||||
```
|
||||
|
||||
## Contacts
|
||||
|
||||
- **Client:** HomeProz Real Estate, LLC - 111 E Clark St, Albert Lea, MN 56007
|
||||
- **MLS Grid Support:** support@mlsgrid.com
|
||||
- **Developer:** HansonXyz - https://hanson.xyz
|
||||
|
||||
Reference in New Issue
Block a user