# Phase 1 Implementation - Final Deployment Guide

## ✅ Implementation Status: COMPLETE

### Branch: `feature/phase-1-auto-push-missing-versions`
### PR: #100
### Commits: 3 (8c76f16, f15e767, 79b3ca5)

---

## 📊 Summary of Changes

### Files Added (7)
```
✅ PHASE_1_ARCHITECTURE.md
✅ PHASE_1_IMPLEMENTATION_SUMMARY.md
✅ PHASE_1_QUICK_START.md
✅ PHASE_1_EXTENDED_SUMMARY.md
✅ KEYS_CONFIG_SERVICE_SUMMARY.md
✅ lib/da_product_app/terminal_management/auto_push_service.ex
✅ lib/da_product_app/terminal_management/keys_config_service.ex
✅ priv/repo/migrations/20250131000001_add_version_columns_to_tms_terminals.exs
✅ priv/repo/migrations/20250131000002_extend_parameter_push_logs_for_configs.exs
✅ priv/repo/migrations/20250131000003_add_keys_config_fields_to_tms_terminals.exs
✅ priv/repo/seeds/device_setup_parameters.exs
```

### Files Modified (4)
```
✅ config/config.exs
✅ lib/da_product_app/mqtt/handler.ex
✅ lib/da_product_app/parameter_management/parameter_push_log.ex
✅ lib/da_product_app/terminal_management/tms_terminal.ex
```

**Total Changes**: 11 files, ~2000+ insertions

---

## 🎯 Features Implemented

### Scenario 1: Missing Version Detection & Auto-Push ✅
- [x] Extract version info from MQTT status messages
- [x] Detect missing versions (NULL or empty strings)
- [x] Trigger auto-push via AutoPushService
- [x] Create audit log entries
- [x] Send MQTT commands to devices

### Device Specific MQTT Commands ✅
- [x] MF919: TMS command format with downloadUrl
- [x] SR600: File download format with metadata
- [x] Kozen: SR600-based format
- [x] Single builder for all device types

### Keys Configuration Management ✅
- [x] RKI key fetching from external endpoint
- [x] keys.json file generation and storage
- [x] kek_kcv field for key management
- [x] slot_number field for device configuration
- [x] Proper MQTT command for keys loading

### Database Schema ✅
- [x] Version tracking columns (3 fields)
- [x] Config type tracking (8 fields)
- [x] Key management fields (2 fields)
- [x] Proper indices for queries
- [x] Audit trail via push logs

### Configuration Management ✅
- [x] RKI endpoint configurable
- [x] OTA base URL configurable
- [x] OTA storage path configurable
- [x] Environment variable support
- [x] Development/Production separation

---

## 📋 Pre-Deployment Checklist

### Code Quality
- [x] Compilation successful: `mix compile`
- [x] No errors or breaking warnings
- [x] Code follows project conventions
- [x] All modules properly documented
- [x] Error handling implemented

### Database Migrations
- [x] Migration 1: Version columns with indices
- [x] Migration 2: Config type tracking fields
- [x] Migration 3: Key management fields
- [x] Seed file: Device Setup parameters
- [x] Backward compatible design

### Documentation
- [x] Architecture diagram created
- [x] Implementation guide documented
- [x] Quick-start guide for testing
- [x] KeysConfigService documented
- [x] Extended summary provided

### Configuration
- [x] config.exs updated with new settings
- [x] Environment variables documented
- [x] Development defaults specified
- [x] Production guidelines provided

---

## 🚀 Deployment Instructions

### Step 1: Pull Latest Code
```bash
cd /home/prem/mercurypay/tmsuat
git fetch origin
git checkout feature/phase-1-auto-push-missing-versions
```

### Step 2: Verify Compilation
```bash
mix compile
```

**Expected Output**: `Generated da_product_app app` (warnings OK)

### Step 3: Run Database Migrations
```bash
mix ecto.migrate
```

**Expected**: 3 migrations applied:
- `add_version_columns_to_tms_terminals`
- `extend_parameter_push_logs_for_configs`
- `add_keys_config_fields_to_tms_terminals`

### Step 4: Seed Device Setup Parameters
```bash
mix run priv/repo/seeds/device_setup_parameters.exs
```

**Expected Output**: 
```
Seeded Device Setup category
Seeded parameter definitions
```

### Step 5: Create OTA Directory
```bash
mkdir -p priv/ota
chmod 755 priv/ota
```

### Step 6: Configure Environment (if needed)
```bash
# Optional - use defaults if not specified
export RKI_ENDPOINT="http://localhost:8300/api/v1/getRki"
export OTA_BASE_URL="http://demo.ctrmv.com/ota"
export OTA_STORAGE_PATH="priv/ota"
```

### Step 7: Restart Application
```bash
# Stop current process
# Then restart
mix phx.server
```

### Step 8: Verify Startup
```bash
# Check logs for successful startup
tail -f logs/app.log | grep -E "(AutoPush|KeysConfig)"
```

---

## ✅ Post-Deployment Verification

### Database Verification
```bash
# Check new columns added
mysql> SELECT serial_number, parameter_config_version, kek_kcv, slot_number 
       FROM tms_terminals LIMIT 1;

# Check seed data
mysql> SELECT * FROM parameter_categories WHERE code = 'device_setup';
mysql> SELECT key FROM parameter_definitions WHERE category_id = <device_setup_id>;

# Check push logs structure
mysql> SHOW COLUMNS FROM parameter_push_logs WHERE Field IN ('config_type', 'device_vendor', 'trigger_reason');
```

### File System Verification
```bash
# Check OTA directory
ls -la priv/ota/
ls -la priv/ota/*/keys.json  # Will be empty until first push

# Check permissions
stat priv/ota/
```

### Application Startup Checks
```bash
# Check for errors in logs
grep -i "error" logs/app.log

# Check MQTT connection
grep -i "mqtt" logs/app.log

# Check service initialization
grep -i "AutoPushService\|KeysConfigService" logs/app.log
```

---

## 🧪 Manual Testing Scenario

### Test: Send MQTT Status with Missing Versions

**Prerequisites:**
- Device template exists for vendor "MoreFun" and model "MF919"
- MQTT broker is running and accessible
- Application is running

**Step 1: Prepare Test Message**
```json
{
  "oid": "org_123",
  "sn": "61250904380091",
  "vendor": "MoreFun",
  "model": "MF919",
  "uploadTime": "2025-01-31T15:00:00Z",
  "org.device": [
    {
      "itemkey": "parameter_config",
      "value": "",
      "timestamp": "2025-01-31T15:00:00Z",
      "message": "Parameter Config"
    },
    {
      "itemkey": "emv_config",
      "value": null,
      "timestamp": "2025-01-31T15:00:00Z",
      "message": "EMV Config"
    },
    {
      "itemkey": "keys_config",
      "value": "",
      "timestamp": "2025-01-31T15:00:00Z",
      "message": "Keys Config"
    },
    {
      "itemkey": "application",
      "value": null,
      "timestamp": "2025-01-31T15:00:00Z",
      "message": "Application"
    }
  ]
}
```

**Step 2: Send Message**
```bash
mosquitto_pub -h <broker_ip> -p 8883 \
  -t tms/status/testDevice \
  -m '<json_from_step_1>'
```

**Step 3: Monitor Logs**
```bash
# Terminal 1: Watch logs
tail -f logs/app.log | grep -E "(AutoPush|KeysConfig|MQTT)"

# Expected output:
# AutoPushService: Triggering auto-push for 61250904380091
# KeysConfigService: Generating keys.json for 61250904380091 (MF919)
# KeysConfigService: Calling getRki endpoint
# AutoPushService: Sending parameter push to 61250904380091
# AutoPushService: Sending keys config to 61250904380091
```

**Step 4: Verify Database**
```sql
-- Check 4 push log entries created
SELECT config_type, trigger_reason, status, request_id
FROM parameter_push_logs
WHERE device_vendor = 'MoreFun' AND device_model = 'MF919'
ORDER BY created_at DESC LIMIT 4;

-- Expected rows: parameter, emv_config, keys_config, application
```

**Step 5: Verify File Creation**
```bash
# Check keys.json was created
ls -la priv/ota/61250904380091/
cat priv/ota/61250904380091/keys.json

# Should contain:
# {
#   "rki_key": "...",
#   "rki_kcv": "...",
#   "slot_number": 1,
#   "serial_number": "61250904380091",
#   "created_at": "..."
# }
```

---

## 🔍 Troubleshooting

### Issue: Migrations fail
```bash
# Check migration history
mix ecto.migrations

# Rollback if needed
mix ecto.rollback --step 3

# Re-run
mix ecto.migrate
```

### Issue: getRki endpoint unreachable
```bash
# Check configuration
grep -i "rki_endpoint" config/config.exs

# Verify endpoint is running
curl http://localhost:8300/api/v1/getRki \
  -H "Content-Type: application/json" \
  -d '{"serialNumber":"test","model":"MF919","kekKcv":"112233","slotNumber":1}'
```

### Issue: keys.json not created
```bash
# Check permissions on priv/ota/
ls -la priv/ota/

# Check logs for KeysConfigService errors
grep "KeysConfigService" logs/app.log | grep -i error

# Ensure OTA directory exists
mkdir -p priv/ota
chmod 755 priv/ota
```

### Issue: MQTT commands not sent
```bash
# Check MQTT connection
grep -i "mqtt\|tortoise" logs/app.log

# Check device subscription
mosquitto_sub -h <broker> -p 8883 -t '/ota/+/+/update' -v

# Then send test MQTT message again
```

---

## 📚 Documentation Files

All documentation available in repository:

1. **PHASE_1_EXTENDED_SUMMARY.md** - Complete technical overview
2. **PHASE_1_ARCHITECTURE.md** - System architecture & data flows
3. **PHASE_1_IMPLEMENTATION_SUMMARY.md** - Implementation details
4. **PHASE_1_QUICK_START.md** - Quick deployment & testing
5. **KEYS_CONFIG_SERVICE_SUMMARY.md** - KeysConfigService specifics

---

## 📞 Support & Next Steps

### After Successful Deployment
1. Monitor application logs for 24 hours
2. Send test MQTT messages to verify auto-push
3. Verify keys.json files are being created
4. Check database audit trail entries

### Phase 2 Planning
- Version mismatch detection (device vs latest)
- Scheduled version management
- Automated version updates

### Questions?
Refer to:
- [PHASE_1_EXTENDED_SUMMARY.md](PHASE_1_EXTENDED_SUMMARY.md)
- [KEYS_CONFIG_SERVICE_SUMMARY.md](KEYS_CONFIG_SERVICE_SUMMARY.md)
- [PHASE_1_QUICK_START.md](PHASE_1_QUICK_START.md)

---

## 🎯 Final Checklist

Before merging to main:
- [ ] Code review completed
- [ ] All tests pass
- [ ] Database migrations verified
- [ ] Configuration documented
- [ ] Manual testing completed
- [ ] Team approval received

After merge to main:
- [ ] Deploy to staging environment
- [ ] Run complete test suite
- [ ] Monitor for 24 hours
- [ ] Deploy to production
- [ ] Monitor production logs
- [ ] Notify team of deployment

---

**Status**: ✅ READY FOR DEPLOYMENT  
**PR #100**: Ready for review and merge  
**Phase 1 Complete**: YES  
**Phase 2 Ready**: YES (after deployment verification)

---

Generated: 2025-01-31
Branch: feature/phase-1-auto-push-missing-versions