Add pitfall #7 (recommendation format bug) + diagnostic script reference

After 8 hours of silent signal swallowing, document:
- Root cause: watcher expected "ENTER:" prefix but bot writes "side:phase:strength"
- Discovery method: analyze.sh recommendation distribution shows signals vs pushes
- Fix commit reference: 08560d0
- Three concrete lessons for cross-process data contracts

Also:
- Reference analyze.sh in cheat sheet (信号诊断 command)
- Fix manual test format in cheat sheet (no more ENTER: prefix)
- Add file structure entry for analyze.sh
- Add security checklist item: check real field formats before editing parsers

DEPLOYMENT.md

@@ -351,16 +351,55 @@ if (flipped && cooled && newRow) {
 
 **教训**：远程操作类任务，必须明确"这需要你在服务器执行"。
 
+### 坑 7：watcher 误读 CSV 格式，吞掉全部真信号
+
+**症状**：bot 跑 8 小时，`pm2 logs` 完全正常，但 Telegram 0 条推送。手动测试用 `ENTER:UP:MID:GOOD` 格式能推送成功，造成"系统在工作"的假象。
+
+**根因**：watcher 检查 `recommendation.startsWith("ENTER")`，但 bot 实际写的是 `side:phase:strength`（`src/index.js:721`，无 `ENTER:` 前缀）：
+
+```js
+rec.action === "ENTER" ? `${rec.side}:${rec.phase}:${rec.strength}` : "NO_TRADE"
+// 实际输出: "UP:MID:STRONG"，不是 "ENTER:UP:MID:STRONG"
+```
+
+→ 7,460 条真信号全被 watcher 判定为 NO_TRADE，只有手动测试用的 `ENTER:` 前缀格式才会触发。
+
+**发现方式**：用 `analyze.sh` 统计 `signals.csv` 的 recommendation 列分布：
+```
+16271 NO_TRADE
+ 2386 UP:EARLY:STRONG       ← 应该有推送但没推
+ 1539 DOWN:EARLY:STRONG     ← 同上
+ ...
+```
+如果信号明显多于推送 → 100% 是格式解析问题。
+
+**修复**（commit `08560d0`）：用 `rec.includes(":")` 作为 ENTER 标记：
+
+```js
+const isEnter = data.rec.includes(":");
+const side = isEnter ? data.rec.split(":")[0] : null;
+const [, phase, strength] = data.rec.split(":");
+```
+
+**教训**：
+
+1. **跨进程/跨文件的数据格式契约必须对照实际生产者代码确认**，不能从命名/注释推断。
+2. **设计手动测试时，必须用真实生产数据格式**，不能凭直觉编一个"看起来合理"的格式。
+3. **"测试能跑" ≠ "系统在工作"**——这次手动测试能推送，反而掩盖了真信号被吞的事实。
+
 ---
 
 ## 七、文件结构（部署相关）
 
+## 七、文件结构（部署相关）
+
 ```
 /opt/PolymarketBTC15mAssistant/
 ├── .env                      # 密钥，gitignore，chmod 600
 ├── .env.example              # 模板，可提交
 ├── start.sh                  # env wrapper，gitignore
 ├── ecosystem.config.cjs      # PM2 配置，gitignore
+├── analyze.sh                # 诊断脚本（无推送时用）
 ├── logs/
 │   ├── signals.csv           # bot 写的信号日志
 │   ├── polymarket_market_*.json   # 每个市场 dump 一次
@@ -406,6 +445,7 @@ if (flipped && cooled && newRow) {
 - [ ] 没有把含 token 的截图/日志发到聊天软件
 - [ ] 服务器 SSH 只允许密钥登录（关密码登录）
 - [ ] PM2 进程用普通用户跑（不用 root，除非必要）
+- [ ] **修改任何 CSV/JSON 解析逻辑前，先 `head -2 logs/signals.csv` 看真实字段格式**（防坑 7）
 
 ---
 
@@ -425,12 +465,19 @@ pm2 restart polymarket-watcher
 pm2 stop polymarket-bot && pm2 start polymarket-bot
 
 # === 测试推送 ===
+# 注意：格式必须是 side:phase:strength（无 ENTER: 前缀，bot 实际输出格式）
 pm2 stop polymarket-bot && sleep 2 && \
-echo '...ENTER:UP:MID:GOOD' >> logs/signals.csv && \
+echo '2026-07-21T18:00:00Z,12.000,3.000,TREND_UP,BUY UP,0.7,0.3,0.5,0.5,0.2,-0.2,UP:MID:GOOD' >> logs/signals.csv && \
 sleep 3 && \
 pm2 logs polymarket-watcher --nostream --lines 30 | grep -E "slug|sent" && \
 pm2 start polymarket-bot
 
+# === 信号诊断（无推送时先跑这个） ===
+./analyze.sh
+# 输出 recommendation 分布、max edges、各 phase 的 ENTER 频率
+# 真没信号 vs 被吞掉，看 NO_TRADE vs ENTER 类别的比例
+# 如果 ENTER 类别 > 0 但没推送 → 解析/推送链路问题
+
 # === 更新 ===
 git pull && npm install && pm2 restart all