docs: 消息架构重构阶段总结文档+broadcast/messenger spec+INDEX更新

2026-08-22 10:29:19 +08:00
parent fb5a1adcec
commit 0c1c6cabeb
4 changed files with 221 additions and 0 deletions
@@ -0,0 +1,49 @@
+{
+  "module": "broadcast",
+  "purpose": "统一消息播报系统——所有系统消息的唯一数据源与展示",
+  "human_help": {
+    "title": "播报系统",
+    "description": [
+      "播报系统是 MoFin 所有系统消息的唯一数据源。",
+      "所有 cron 脚本产生的消息（交易推荐/系统异常/市场数据/新闻/策略评估）都会写入 broadcast_messages 表。",
+      "播报 Tab 展示最近72小时的消息（分类标签+颜色，点击可查看全文）。",
+      "历史消息页（broadcast.html）支持按日期范围、关键字、类型查询。"
+    ],
+    "usage": [
+      "播报 Tab：主界面查看最近消息，最新在最上。",
+      "分类：trading(交易)/system_error(异常)/health(健康)/market(市场)/news(新闻)/strategy(策略)。",
+      "长消息：表格只显示前120字，点击弹出完整内容。",
+      "历史消息：点击右上角'📋 历史消息'进入查询页。"
+    ],
+    "troubleshooting": [
+      "播报 Tab 显示 Loading：检查 /api/broadcast/recent 是否正常。",
+      "消息缺失：检查对应脚本的 delivery 配置（jobs.json）。",
+      "异常没显示：异常浮窗只显示24小时内的 system_error 类消息。"
+    ]
+  },
+  "ai_spec": {
+    "purpose": "统一消息源 + 播报查询",
+    "apis": [
+      {"method": "GET", "path": "/api/broadcast/recent", "returns": "最近N小时消息列表"},
+      {"method": "GET", "path": "/api/broadcast/search", "returns": "历史消息搜索(start/end/keyword/category)"},
+      {"method": "POST", "path": "/api/broadcast/archive", "returns": "归档超过N天的消息"},
+      {"method": "POST", "path": "/api/broadcast/toggle_delivery", "returns": "切换job消息通道(broadcast/xmpp/both)"}
+    ],
+    "dependencies": ["broadcast_messages表", "messenger.py", "jobs.json delivery配置"],
+    "constraints": [
+      "broadcast_messages 是唯一消息源",
+      "所有脚本通过 messenger 写消息，不直接操作表",
+      "category 由 messenger._classify 自动判定"
+    ],
+    "must_not": [
+      "禁止脚本直接 INSERT broadcast_messages（必须走 messenger）",
+      "禁止绕过 messenger 直接 print 给用户消息"
+    ],
+    "related_files": [
+      "deploy/profile-scripts/broadcast.py",
+      "deploy/profile-scripts/messenger.py",
+      "static/broadcast.html",
+      "static/index.html (播报Tab)"
+    ]
+  }
+}