From 1b9881a706b1d89966663e9a14e7dc5b803ee9d6 Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Mon, 28 Jul 2025 13:49:30 +0200
Subject: [PATCH] docs: add Docker volume mount debugging and Prisma table name
 troubleshooting wisdom

- Add comprehensive Docker volume mount debugging workflow
- Document container vs host file sync issues
- Include Next.js compilation cache troubleshooting
- Add Prisma table name validation steps
- Document silent failure patterns when DB queries fail
- Include debugging steps for price source fallback investigation
---
 .github/copilot-instructions.md | 68 +++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index da28100..fa2505a 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -292,6 +292,31 @@ await prisma.ai_learning_data.create({
 const { getDB } = require('./db');  // NOT './database-util'
 ```
 
+### Prisma Table Name Debugging (Critical)
+**Problem**: Database queries fail with "Cannot read properties of undefined (reading 'findMany')" despite correct syntax.
+
+**Root Cause**: Prisma model names vs database table names can differ, causing silent failures that fall back to alternative APIs (like Binance instead of CoinGecko).
+
+**Common Issues**:
+```javascript
+// ❌ Wrong - will cause undefined errors
+await prisma.trade.findMany()              // Should be 'trades' 
+await prisma.automationSession.findMany()  // Should be 'automation_sessions'
+
+// ✅ Correct - matches actual database schema
+await prisma.trades.findMany()
+await prisma.automation_sessions.findMany()
+```
+
+**Debugging Steps**:
+1. **Check Prisma schema** (`prisma/schema.prisma`) for actual model names
+2. **Verify table names** in database: `PRAGMA table_info(trades);`
+3. **Test queries directly**: `node -e "const prisma = new PrismaClient(); prisma.trades.findMany().then(console.log);"`
+4. **Look for fallback behavior** - API might silently use backup data sources when DB fails
+5. **Monitor logs for price source errors** - DB failures often cause price fetching fallbacks
+
+**Impact**: Database errors can cause price monitors to fail and fall back to wrong price sources (Binance instead of CoinGecko), affecting trading accuracy.
+
 ### Always Include These Functions in Learning Classes:
 ```javascript
 async generateLearningReport() {
@@ -520,6 +545,49 @@ curl -s http://localhost:9001/api/automation/position-monitor | jq .
 node -e "const {getDB} = require('./lib/db'); getDB().then(() => console.log('DB OK'));"
 ```
 
+### Docker Volume Mount Debugging (Critical Learning)
+**Problem**: Code changes don't reflect in container, or container has different file content than host.
+
+**Root Cause**: Volume mounts in `docker-compose.dev.yml` synchronize host directories to container:
+```yaml
+volumes:
+  - ./app:/app/app:cached        # Host ./app → Container /app/app
+  - ./lib:/app/lib:cached        # Host ./lib → Container /app/lib
+```
+
+**Debugging Workflow**:
+```bash
+# 1. Always check what's actually in the container vs host
+docker compose -f docker-compose.dev.yml exec app bash -c "grep -n 'problem_pattern' /app/app/api/file.js"
+grep -n 'problem_pattern' app/api/file.js
+
+# 2. Compare file checksums to verify sync
+sha256sum app/api/file.js
+docker compose -f docker-compose.dev.yml exec app bash -c "sha256sum /app/app/api/file.js"
+
+# 3. Check if Next.js compiled cache is stale
+docker compose -f docker-compose.dev.yml exec app bash -c "ls -la /app/.next/server/"
+docker compose -f docker-compose.dev.yml exec app bash -c "grep -r 'problem_pattern' /app/.next/server/ || echo 'Not in compiled cache'"
+
+# 4. Clear Next.js cache if files match but behavior doesn't
+docker compose -f docker-compose.dev.yml exec app bash -c "rm -rf /app/.next"
+docker compose -f docker-compose.dev.yml restart
+```
+
+**Key Insights**:
+- **Host edits sync to container** automatically via volume mounts
+- **Container file copies are overwritten** by volume mounts on restart
+- **Next.js compilation cache** in `.next/` can persist old code even after file changes
+- **Always verify container content** matches expectations before debugging logic
+- **Compiled webpack bundles** may differ from source files - check both
+
+**Troubleshooting Steps**:
+1. **Verify host file has expected changes** (`grep`, `cat`, `sed -n '90,100p'`)
+2. **Confirm container file matches host** (checksums, direct comparison)
+3. **Check if .next cache is stale** (search compiled files for old patterns)
+4. **Clear compilation cache and restart** if source is correct but behavior wrong
+5. **Use container logs to trace actual execution** vs expected code paths
+
 ## 🚨 Critical Anti-Patterns to Avoid
 
 ### ❌ Don't Do This: