Michael Schiemer
fc3d7e6357
- Add comprehensive health check system with multiple endpoints - Add Prometheus metrics endpoint - Add production logging configurations (5 strategies) - Add complete deployment documentation suite: * QUICKSTART.md - 30-minute deployment guide * DEPLOYMENT_CHECKLIST.md - Printable verification checklist * DEPLOYMENT_WORKFLOW.md - Complete deployment lifecycle * PRODUCTION_DEPLOYMENT.md - Comprehensive technical reference * production-logging.md - Logging configuration guide * ANSIBLE_DEPLOYMENT.md - Infrastructure as Code automation * README.md - Navigation hub * DEPLOYMENT_SUMMARY.md - Executive summary - Add deployment scripts and automation - Add DEPLOYMENT_PLAN.md - Concrete plan for immediate deployment - Update README with production-ready features All production infrastructure is now complete and ready for deployment.
140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# Format Information Placement Fix - Complete Analysis
|
|
|
|
## Problem Discovery
|
|
|
|
QR codes were technically correct (data placement, Reed-Solomon, all function patterns) but **completely unrecognizable** by scanner apps.
|
|
|
|
### Critical Test Result
|
|
- **Python Reference QR Code**: ✅ WORKS (user confirmed: "der python code funktioniert")
|
|
- **Our Implementation**: ❌ FAILED (user confirmed: "der andere nicht")
|
|
|
|
## Root Cause
|
|
|
|
Format Information horizontal placement was **INCORRECT**.
|
|
|
|
### What Was Wrong
|
|
|
|
**Before Fix:**
|
|
- Applied bit swap pattern `[0,1,2,3,4,5,6,7,8,10,9,11,13,12,14]` when WRITING
|
|
- This created DOUBLE swapping (once in bit order, once in column order)
|
|
- Result: Horizontal ≠ Vertical format info
|
|
|
|
```php
|
|
// ❌ WRONG - Double swapping
|
|
$bitIndices = [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 9, 11, 13, 12, 14];
|
|
for ($i = 0; $i < 15; $i++) {
|
|
$bitIndex = $bitIndices[$i]; // First swap
|
|
$bit = ($formatBits >> (14 - $bitIndex)) & 1;
|
|
$matrix = $matrix->setModuleAt(8, $columns[$i], $module); // Second swap in column order
|
|
}
|
|
```
|
|
|
|
### The Fix
|
|
|
|
**After Fix:**
|
|
- Write bits SEQUENTIALLY (0-14)
|
|
- Let the COLUMN ORDER create the natural swap
|
|
- Result: Horizontal = Vertical format info ✅
|
|
|
|
```php
|
|
// ✅ CORRECT - Sequential placement
|
|
for ($i = 0; $i < 15; $i++) {
|
|
$bit = ($formatBits >> (14 - $i)) & 1; // Sequential bits
|
|
$module = $bit === 1 ? Module::dark() : Module::light();
|
|
$matrix = $matrix->setModuleAt(8, $columns[$i], $module); // Column order creates natural swap
|
|
}
|
|
```
|
|
|
|
## Technical Details
|
|
|
|
### Format Information Structure
|
|
- 15 bits total
|
|
- Bits 0-4: EC level + Mask pattern (5 data bits)
|
|
- Bits 5-14: BCH(15,5) error correction (10 parity bits)
|
|
- XOR mask: `101010000010010`
|
|
|
|
### Placement Columns (Horizontal)
|
|
```
|
|
[0, 1, 2, 3, 4, 5, 7, 8, 20, 19, 18, 17, 16, 15, 14]
|
|
^ ^ ↓- ↓- ↓- ↓- ↓- ↓- ↓-
|
|
(skip 6 - timing separator)
|
|
(right-to-left order creates swap effect)
|
|
```
|
|
|
|
### Verification Results
|
|
|
|
**Before Fix:**
|
|
```
|
|
Horizontal: 101111001111010
|
|
Vertical: 101111001111100
|
|
Match: ❌
|
|
```
|
|
|
|
**After Fix:**
|
|
```
|
|
Horizontal: 101111001111100
|
|
Vertical: 101111001111100
|
|
Match: ✅ PERFECT!
|
|
```
|
|
|
|
## Why This Matters
|
|
|
|
Format information tells the scanner:
|
|
1. Which error correction level to use
|
|
2. Which mask pattern was applied to data
|
|
|
|
**Without correct format info:**
|
|
- Scanner can't decode the mask pattern
|
|
- Data appears corrupted
|
|
- QR code is completely unreadable
|
|
|
|
**With correct format info:**
|
|
- Scanner knows how to unmask data
|
|
- Error correction works properly
|
|
- QR code scans successfully
|
|
|
|
## Files Changed
|
|
|
|
### `/home/michael/dev/michaelschiemer/src/Framework/QrCode/Structure/FormatInformation.php`
|
|
|
|
**Method:** `applyFormatBitsHorizontal()` (lines 105-120)
|
|
|
|
**Change:**
|
|
- Removed `$bitIndices` array
|
|
- Changed from `$bitIndices[$i]` to sequential `$i`
|
|
- Updated comment to explain column order creates swap
|
|
|
|
## Testing
|
|
|
|
### Test Files Created
|
|
1. `tests/debug/generate-reference-qr.py` - Python reference QR code
|
|
2. `tests/debug/compare-matrices.php` - Bit-by-bit comparison
|
|
3. `tests/debug/decode-python-format.php` - Reverse engineer Python's placement
|
|
4. `tests/debug/find-horizontal-pattern.php` - Discovered bit mapping
|
|
5. `tests/debug/debug-last-bits.php` - Debug specific bit positions
|
|
6. `tests/debug/analyze-horizontal-issue.php` - Identified double-swap problem
|
|
7. `tests/debug/final-verification.php` - Complete verification
|
|
|
|
### Generated QR Codes
|
|
1. `public/qrcode-python-large.png` - Python reference (✅ WORKS)
|
|
2. `public/qrcode-CORRECTED.png` - After initial fix attempt
|
|
3. `public/qrcode-FINAL.png` - After complete fix (✅ SHOULD WORK)
|
|
|
|
## Next Steps
|
|
|
|
**User Testing Required:**
|
|
Test `qrcode-FINAL.png` with smartphone scanner:
|
|
- URL: https://localhost/qrcode-FINAL.png
|
|
- Expected result: Decodes to "HELLO WORLD"
|
|
|
|
If successful, QR code implementation is COMPLETE! ✅
|
|
|
|
## Lessons Learned
|
|
|
|
1. **Don't assume bit placement patterns** - verify against working reference
|
|
2. **Column/Row order matters** - can create implicit swapping
|
|
3. **Test with real scanners** - technical correctness ≠ scanner compatibility
|
|
4. **Python qrcode library is excellent reference** - ISO-compliant and battle-tested
|
|
5. **Format information is critical** - without it, nothing else matters
|
|
|