docs: Major documentation reorganization + ENV variable reference
**Documentation Structure:** - Created docs/ subdirectory organization (analysis/, architecture/, bugs/, cluster/, deployments/, roadmaps/, setup/, archived/) - Moved 68 root markdown files to appropriate categories - Root directory now clean (only README.md remains) - Total: 83 markdown files now organized by purpose **New Content:** - Added comprehensive Environment Variable Reference to copilot-instructions.md - 100+ ENV variables documented with types, defaults, purpose, notes - Organized by category: Required (Drift/RPC/Pyth), Trading Config (quality/ leverage/sizing), ATR System, Runner System, Risk Limits, Notifications, etc. - Includes usage examples (correct vs wrong patterns) **File Distribution:** - docs/analysis/ - Performance analyses, blocked signals, profit projections - docs/architecture/ - Adaptive leverage, ATR trailing, indicator tracking - docs/bugs/ - CRITICAL_*.md, FIXES_*.md bug reports (7 files) - docs/cluster/ - EPYC setup, distributed computing docs (3 files) - docs/deployments/ - *_COMPLETE.md, DEPLOYMENT_*.md status (12 files) - docs/roadmaps/ - All *ROADMAP*.md strategic planning files (7 files) - docs/setup/ - TradingView guides, signal quality, n8n setup (8 files) - docs/archived/2025_pre_nov/ - Obsolete verification checklist (1 file) **Key Improvements:** - ENV variable reference: Single source of truth for all configuration - Common Pitfalls #68-71: Already complete, verified during audit - Better findability: Category-based navigation vs 68 files in root - Preserves history: All files git mv (rename), not copy/delete - Zero broken functionality: Only documentation moved, no code changes **Verification:** - 83 markdown files now in docs/ subdirectories - Root directory cleaned: 68 files → 0 files (except README.md) - Git history preserved for all moved files - Container running: trading-bot-v4 (no restart needed) **Next Steps:** - Create README.md files in each docs subdirectory - Add navigation index - Update main README.md with new structure - Consolidate duplicate deployment docs - Archive truly obsolete files (old SQL backups) See: docs/analysis/CLEANUP_PLAN.md for complete reorganization strategy
This commit is contained in:
mindesbunister
262
docs/deployments/TP1_FIX_DEPLOYMENT_SUMMARY.md
Normal file
262
docs/deployments/TP1_FIX_DEPLOYMENT_SUMMARY.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# TP1 False Detection Fix - Deployment Summary
|
||||
|
||||
**Date:** November 30, 2025, 22:09 UTC (23:09 CET)
|
||||
**Status:** ✅ DEPLOYED AND VERIFIED
|
||||
**Severity:** 🔴 CRITICAL - Financial loss prevention
|
||||
|
||||
## Issues Fixed
|
||||
|
||||
### 1. ✅ FALSE TP1 DETECTION BUG (CRITICAL)
|
||||
**Symptom:** Position Manager detected TP1 hit before price reached target, causing premature order cancellation
|
||||
|
||||
**Root Cause:** Line 1086 in lib/trading/position-manager.ts
|
||||
```typescript
|
||||
// BROKEN CODE:
|
||||
trade.tp1Hit = true // Set without verifying price crossed TP1 target!
|
||||
```
|
||||
|
||||
**Fix Applied:** Added price verification
|
||||
```typescript
|
||||
// FIXED CODE:
|
||||
const tp1PriceReached = this.shouldTakeProfit1(currentPrice, trade)
|
||||
if (tp1PriceReached) {
|
||||
trade.tp1Hit = true // Only set when BOTH size reduced AND price crossed
|
||||
// ... verbose logging ...
|
||||
} else {
|
||||
// Update size but don't trigger TP1 logic
|
||||
trade.currentSize = positionSizeUSD
|
||||
// ... continue monitoring ...
|
||||
}
|
||||
```
|
||||
|
||||
**File:** lib/trading/position-manager.ts (lines 1082-1111)
|
||||
**Commit:** 78757d2
|
||||
**Deployed:** 2025-11-30T22:09:18Z
|
||||
|
||||
### 2. ✅ TELEGRAM BOT /STATUS COMMAND
|
||||
**Symptom:** `/status` command not responding
|
||||
**Root Cause:** Multiple bot instances causing conflict: "Conflict: terminated by other getUpdates request"
|
||||
**Fix Applied:** Restarted telegram-trade-bot container
|
||||
**Status:** ✅ Fixed
|
||||
|
||||
## Verification
|
||||
|
||||
### Deployment Timeline
|
||||
```
|
||||
22:08:02 UTC - Container started (first attempt, wrong code)
|
||||
23:08:34 CET - Git commit with fix
|
||||
22:09:18 UTC - Container restarted with fix (DEPLOYED)
|
||||
```
|
||||
|
||||
**Container Start:** 2025-11-30T22:09:18.881918159Z
|
||||
**Latest Commit:** 2025-11-30 23:08:34 +0100 (78757d2)
|
||||
**Verification:** ✅ Container NEWER than commit
|
||||
|
||||
### Expected Behavior
|
||||
**Next trade with TP1 will show:**
|
||||
|
||||
**If size reduces but price NOT at target:**
|
||||
```
|
||||
⚠️ Size reduced but TP1 price NOT reached yet - NOT triggering TP1 logic
|
||||
Current: 137.50, TP1 target: 137.07 (need lower)
|
||||
Size: $89.10 → $22.27 (25.0%)
|
||||
Likely: Partial fill, slippage, or external action
|
||||
```
|
||||
|
||||
**If size reduces AND price crossed target:**
|
||||
```
|
||||
✅ TP1 VERIFIED: Size mismatch + price target reached
|
||||
Size: $89.10 → $22.27 (25.0%)
|
||||
Price: 137.05 crossed TP1 target 137.07
|
||||
🎉 TP1 HIT: SOL-PERP via on-chain order (detected by size reduction)
|
||||
```
|
||||
|
||||
## Real Incident Details
|
||||
|
||||
**Trade ID:** cmim4ggkr00canv07pgve2to9
|
||||
**Symbol:** SOL-PERP SHORT
|
||||
**Entry:** $137.76 at 19:37:14 UTC
|
||||
**TP1 Target:** $137.07 (0.5% profit)
|
||||
**Actual Exit:** $136.84 at 21:22:27 UTC
|
||||
**P&L:** $0.23 (+0.50%)
|
||||
|
||||
**What Went Wrong:**
|
||||
1. Position Manager detected size mismatch
|
||||
2. Immediately set `tp1Hit = true` WITHOUT checking price
|
||||
3. Triggered phase 2 logic (breakeven SL, order cancellation)
|
||||
4. On-chain TP1 order cancelled prematurely
|
||||
5. Container restart during trade caused additional confusion
|
||||
6. Lucky outcome: TP1 order actually filled before cancellation
|
||||
|
||||
**Impact:**
|
||||
- System integrity compromised
|
||||
- Ghost orders accumulating
|
||||
- Potential profit loss if order cancelled before fill
|
||||
- User received only 1 Telegram notification (missing entry, runner exit)
|
||||
|
||||
## Files Changed
|
||||
|
||||
### 1. lib/trading/position-manager.ts
|
||||
**Lines:** 1082-1111 (size mismatch detection block)
|
||||
**Changes:**
|
||||
- Added `this.shouldTakeProfit1(currentPrice, trade)` verification
|
||||
- Only set `trade.tp1Hit = true` when BOTH conditions met
|
||||
- Added verbose logging for debugging
|
||||
- Fallback: Update size without triggering TP1 logic
|
||||
|
||||
### 2. CRITICAL_TP1_FALSE_DETECTION_BUG.md (NEW)
|
||||
**Purpose:** Comprehensive incident report and fix documentation
|
||||
**Contents:**
|
||||
- Bug chain sequence
|
||||
- Real incident details
|
||||
- Root cause analysis
|
||||
- Fix implementation
|
||||
- Verification steps
|
||||
- Prevention measures
|
||||
|
||||
## Testing Required
|
||||
|
||||
### Monitor Next Trade
|
||||
**Watch for these logs:**
|
||||
```bash
|
||||
docker logs -f trading-bot-v4 | grep -E "(TP1 VERIFIED|TP1 price NOT reached|TP1 HIT)"
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
- ✅ TP1 only triggers when price crosses target
|
||||
- ✅ Size reduction alone doesn't trigger TP1
|
||||
- ✅ Verbose logging shows price vs target comparison
|
||||
- ✅ No premature order cancellation
|
||||
- ✅ On-chain orders remain active until proper fill
|
||||
|
||||
### SQL Verification
|
||||
```sql
|
||||
-- Check next TP1 trade for correct flags
|
||||
SELECT
|
||||
id,
|
||||
symbol,
|
||||
direction,
|
||||
entryPrice,
|
||||
exitPrice,
|
||||
tp1Price,
|
||||
tp1Hit,
|
||||
tp1Filled,
|
||||
exitReason,
|
||||
TO_CHAR(createdAt, 'MM-DD HH24:MI') as entry_time,
|
||||
TO_CHAR(exitTime, 'MM-DD HH24:MI') as exit_time
|
||||
FROM "Trade"
|
||||
WHERE exitReason IS NOT NULL
|
||||
AND createdAt > NOW() - INTERVAL '24 hours'
|
||||
ORDER BY createdAt DESC
|
||||
LIMIT 5;
|
||||
```
|
||||
|
||||
## Outstanding Issues
|
||||
|
||||
### 3. ⚠️ MISSING TELEGRAM NOTIFICATIONS
|
||||
**Status:** NOT YET FIXED
|
||||
**Details:** Only TP1 close notification sent, missing entry/runner/status
|
||||
**Investigation Needed:**
|
||||
- Check lib/notifications/telegram.ts integration points
|
||||
- Verify notification calls in app/api/trading/execute/route.ts
|
||||
- Test notification sending after bot restart
|
||||
|
||||
### 4. ⚠️ CONTAINER RESTART ORDER CONFUSION
|
||||
**Status:** NOT YET INVESTIGATED
|
||||
**Details:** Multiple restarts during active trade caused duplicate orders
|
||||
**User Report:** "system didn't recognize actual status and put in a 'Normal' stop loss and another tp1"
|
||||
**Investigation Needed:**
|
||||
- Review lib/startup/init-position-manager.ts orphan detection
|
||||
- Understand order placement during position restoration
|
||||
- Test restart scenarios with active trades
|
||||
|
||||
## Git Commit Details
|
||||
|
||||
**Commit:** 78757d2
|
||||
**Message:** critical: Fix FALSE TP1 detection - add price verification (Pitfall #63)
|
||||
|
||||
**Full commit message includes:**
|
||||
- Bug description
|
||||
- Root cause analysis
|
||||
- Fix implementation details
|
||||
- Real incident details
|
||||
- Testing requirements
|
||||
- Related fixes (Telegram bot restart)
|
||||
|
||||
**Pushed to remote:** ✅ Yes
|
||||
|
||||
## Documentation Updates Required
|
||||
|
||||
### 1. copilot-instructions.md
|
||||
**Add Common Pitfall #63:**
|
||||
```markdown
|
||||
63. **TP1 False Detection via Size Mismatch (CRITICAL - Fixed Nov 30, 2025):**
|
||||
- **Symptom:** Position Manager cancels TP1 orders prematurely
|
||||
- **Root Cause:** Size reduction assumed to mean TP1 hit, no price verification
|
||||
- **Bug Location:** lib/trading/position-manager.ts line 1086
|
||||
- **Fix:** Always verify BOTH size reduction AND price target reached
|
||||
- **Code:**
|
||||
```typescript
|
||||
const tp1PriceReached = this.shouldTakeProfit1(currentPrice, trade)
|
||||
if (tp1PriceReached) {
|
||||
trade.tp1Hit = true // Only when verified
|
||||
}
|
||||
```
|
||||
- **Impact:** Lost profit potential from premature exits
|
||||
- **Detection:** Log shows "TP1 hit: true" but price never reached TP1 target
|
||||
- **Real Incident:** Trade cmim4ggkr00canv07pgve2to9 (Nov 30, 2025)
|
||||
- **Commit:** 78757d2
|
||||
- **Files:** lib/trading/position-manager.ts (lines 1082-1111)
|
||||
```
|
||||
|
||||
### 2. When Making Changes Section
|
||||
**Add to Rule 10 (Position Manager changes):**
|
||||
```markdown
|
||||
- **CRITICAL:** Never set tp1Hit flag without verifying price crossed target
|
||||
- Size mismatch detection MUST check this.shouldTakeProfit1(currentPrice, trade)
|
||||
- Only trigger TP1 logic when BOTH conditions met: size reduced AND price verified
|
||||
- Add verbose logging showing price vs target comparison
|
||||
- Test with trades where size reduces but price hasn't crossed TP1 yet
|
||||
```
|
||||
|
||||
## User Communication
|
||||
|
||||
**Status Summary:**
|
||||
✅ CRITICAL BUG FIXED: False TP1 detection causing premature order cancellation
|
||||
✅ Telegram bot restarted: /status command should work now
|
||||
⚠️ Monitoring required: Watch next trade for correct TP1 detection
|
||||
⚠️ Outstanding: Missing notifications (entry, runner) need investigation
|
||||
⚠️ Outstanding: Container restart order duplication needs investigation
|
||||
|
||||
**What to Watch:**
|
||||
- Next trade with TP1: Check logs for "TP1 VERIFIED" message
|
||||
- Verify on-chain orders remain active until proper fill
|
||||
- Test /status command in Telegram
|
||||
- Report if any notifications still missing
|
||||
|
||||
**Next Steps:**
|
||||
1. Monitor next trade closely
|
||||
2. Verify TP1 detection works correctly
|
||||
3. Investigate missing notifications
|
||||
4. Investigate container restart order issue
|
||||
5. Update copilot-instructions.md with Pitfall #63
|
||||
|
||||
## Conclusion
|
||||
|
||||
**CRITICAL FIX DEPLOYED:** ✅
|
||||
**Container restarted:** 2025-11-30T22:09:18Z
|
||||
**Code committed & pushed:** 78757d2
|
||||
**Verification complete:** Container running new code
|
||||
|
||||
**System now protects against:**
|
||||
- False TP1 detection from size mismatch alone
|
||||
- Premature order cancellation
|
||||
- Lost profit opportunities
|
||||
- Ghost order accumulation
|
||||
|
||||
**Monitoring required:**
|
||||
- Watch next trade for correct behavior
|
||||
- Verify TP1 only triggers when price verified
|
||||
- Confirm no premature order cancellation
|
||||
|
||||
**This was a CRITICAL financial safety bug. System integrity restored.**
|
||||
Reference in New Issue
Block a user