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

specs/broadcast.json

@@ -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)"
+    ]
+  }
+}

specs/messenger.json

@@ -0,0 +1,46 @@
+{
+  "module": "messenger",
+  "purpose": "统一消息处理者——生产者与消费者解耦，按 job 配置路由消息通道",
+  "human_help": {
+    "title": "统一消息处理者",
+    "description": [
+      "messenger 是 MoFin 的统一消息处理者。所有脚本发送消息时调用 messenger，不需要关心消息去哪个通道。",
+      "消息去向由【生产者是谁】（哪个 cron job）决定，配置在 jobs.json 的 delivery 字段。",
+      "通道：broadcast(只写播报表) / xmpp(推用户+归档) / both(两者)。"
+    ],
+    "usage": [
+      "脚本接入：文件开头加 from messenger import install_stdio_hook; install_stdio_hook()",
+      "发送消息：messenger.send(title=..., content=..., source=脚本名)",
+      "通道配置：健康 Tab cron 列表的'消息通道'列点击切换。",
+      "操作推荐：messenger.send_action_recommendation() 强制走 xmpp。"
+    ],
+    "troubleshooting": [
+      "消息没推 xmpp：检查该脚本的 delivery 配置是否为 broadcast。",
+      "消息没进播报：检查 messenger 是否正确安装 hook。",
+      "递归嵌套：已修复（写表直接操作DB不经send）。"
+    ]
+  },
+  "ai_spec": {
+    "purpose": "消息生产者与消费者解耦，统一通道路由",
+    "apis": [
+      {"method": "fn", "path": "messenger.send(title, content, source, channel, job_name)", "returns": "通道(broadcast/xmpp)"},
+      {"method": "fn", "path": "messenger.send_action_recommendation(title, content, source)", "returns": "强制xmpp"},
+      {"method": "fn", "path": "messenger.install_stdio_hook(script_name)", "returns": "当前通道"},
+      {"method": "fn", "path": "messenger.get_channel(script)", "returns": "脚本通道配置"}
+    ],
+    "dependencies": ["jobs.json delivery", "broadcast_messages表"],
+    "constraints": [
+      "消费者按生产者(job)判通道，不按内容",
+      "所有通道都写 broadcast_messages 归档",
+      "xmpp 通道输出 stdout 供 hermes 捕获推 xmpp"
+    ],
+    "must_not": [
+      "禁止按消息内容决定通道（内容分类仅用于 broadcast 表展示）",
+      "禁止脚本绕过 messenger 直接 print 用户消息"
+    ],
+    "related_files": [
+      "deploy/profile-scripts/messenger.py",
+      "hermes jobs.json (delivery字段)"
+    ]
+  }
+}