24 KiB
24 KiB
WXAuto Center 业务流程文档
概述
本文档详细描述 WXAuto Center 的核心业务流程，包括消息发送流程、回调重置流程、监控告警流程、健康检测流程和日志发布订阅流程。
1. 节点标识系统
1.1 node_id 与 name 的区别
每个节点有两个标识：
| 字段 | 说明 | 示例 | 用途 |
|---|---|---|---|
| node_id | 节点唯一标识 | "wx1", "node_001" | API 调用、系统内部引用 |
| name | 节点显示名称 | "微信1", "测试节点" | 界面展示、用户友好提示 |
1.2 节点数据模型
{
"node_id": "wx1",
"name": "微信1",
"api_url": "http://192.168.20.18:5000",
"api_key": "key",
"enabled": true,
"description": "",
"group": "wechat",
"status": "active",
"wechat_status": "online",
"is_healthy": true
}
2. 消息发送流程
2.1 流程图
外部请求
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /api/v1/messages/send │
│ 或 │
│ POST /api/v1/external/send │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ check_node_health(node_id) │
│ 调用 /api/wechat/initialize 检测微信状态 │
└─────────────────────────────────────────────────────────────┘
│
├──► 微信状态异常?
│ │
│ ▼ (是)
│ 返回 HTTP 503
│ "Node 'wx1' is not healthy..."
│ │
│ ▼
│ 流程结束
│
▼ (否)
┌─────────────────────────────────────────────────────────────┐
│ node_manager.send_message(node_id, who, msg, msg_type) │
└─────────────────────────────────────────────────────────────┘
│
├──► POST /api/wechat/initialize (初始化微信)
│
└──► POST /api/message/send (发送消息)
│
▼
发送成功?
│
├──► 是 → wechat_status = "online"
│ │
│ ▼
│ 返回成功响应
│
└──► 否 → wechat_status = "offline"
│
▼
返回错误响应
2.2 详细步骤说明
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 接收发送消息请求 | 解析 node_id, who, msg, msg_type |
| 2 | 健康检测 | 调用 is_node_healthy() 检测节点 |
| 3 | 初始化微信 | 调用 /api/wechat/initialize |
| 4 | 发送消息 | 调用 /api/message/send |
| 5 | 更新状态 | 根据发送结果更新 wechat_status |
| 6 | 返回响应 | 返回发送结果给客户端 |
2.3 代码逻辑
async def send_message(node_id: str, who: str, msg: str, msg_type: str = "text"):
# 1. 检查节点是否健康
is_healthy, health_msg = await node_manager.is_node_healthy(node_id)
if not is_healthy:
raise HTTPException(
status_code=503,
detail=f"Node '{node_id}' is not healthy: {health_msg}"
)
# 2. 初始化微信
await node_manager.call_node_api(node_id, "/api/wechat/initialize", method="POST")
# 3. 发送消息
result = await node_manager.call_node_api(
node_id,
"/api/message/send",
method="POST",
data={"receiver": who, "message": msg}
)
# 4. 更新状态
if result.get("code") == 0:
node_manager.update_node_status(node_id, wechat_status="online")
else:
node_manager.update_node_status(node_id, wechat_status="offline")
return result
3. 回调重置流程
3.1 流程图
外部节点回调
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /api/v1/callback/node/reset │
│ 请求体: {"node_id": "wx1"} │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 调用 /api/wechat/initialize 初始化微信 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 调用 /api/message/send 发送检测消息到"文件传输助手" │
│ receiver: "filehelper" │
│ message: "WXAuto Center 检测消息" │
└─────────────────────────────────────────────────────────────┘
│
▼
检测结果
│
├──► 发送成功
│ │
│ ▼
│ wechat_status = "online"
│ │
│ ▼
│ 返回 {"success": true, "wechat_status": "online"}
│
└──► 发送失败
│
▼
wechat_status = "offline"
│
▼
返回 {"success": false, "wechat_status": "offline"}
│
▼
MonitorService 检测到状态变化
│
▼
触发 Webhook 告警 (wechat_offline)
3.2 详细步骤说明
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 接收重置请求 | 解析 node_id |
| 2 | 初始化微信 | 调用 /api/wechat/initialize |
| 3 | 发送检测消息 | 发送消息到文件传输助手(filehelper) |
| 4 | 判断结果 | 根据发送是否成功设置状态 |
| 5 | 触发告警 | 状态变化时触发 Webhook |
3.3 回调接口说明
POST /api/v1/callback/node/reset
用于重置节点的微信状态。当微信掉线后，可以通过此接口重新检测微信状态。
请求体：
{
"node_id": "wx1"
}
响应示例 - 成功：
{
"success": true,
"message": "微信状态已重置",
"data": {
"node_id": "wx1",
"wechat_status": "online",
"check_result": "success"
}
}
响应示例 - 失败：
{
"success": false,
"message": "微信状态检测失败",
"data": {
"node_id": "wx1",
"wechat_status": "offline",
"check_result": "failed",
"error": "Unknown error"
}
}
4. 监控告警流程
4.1 流程图
MonitorService 启动
│
▼
┌─────────────────────────────────────────────────────────────┐
│ _monitor_loop() 定时循环 │
│ 间隔: check_interval (默认 60 秒) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ _check_all_nodes() │
│ 遍历所有节点 │
└─────────────────────────────────────────────────────────────┘
│
▼
对每个节点执行 _check_node(node_id):
│
├──► api_check_enabled?
│ │
│ ▼ (是)
│ check_node_status(node_id)
│ │
│ ▼
│ API 状态变化?
│ │
│ ├──► 是 → 触发 Webhook (node_online/node_offline)
│ │
│ └──► 否 → 无操作
│
└──► wechat_check_enabled?
│
▼ (是)
initialize_wechat(node_id)
│
▼
get_wechat_status(node_id)
│
▼
微信状态变化?
│
├──► 是 → 触发 Webhook (wechat_online/wechat_offline)
│
└──► 否 → 无操作
4.2 支持的事件类型
| 事件类型 | 触发条件 | 消息内容 |
|---|---|---|
| api_error | API 调用失败 | "API Error: {error}" |
| wechat_offline | 微信状态变为 offline | "微信掉线" |
| wechat_online | 微信状态变为 online/connected | "微信上线" |
| node_offline | 节点 API 不可用 | "节点离线" |
| node_online | 节点 API 恢复可用 | "节点在线" |
4.3 Webhook 消息格式
企业微信格式：
{
"msgtype": "text",
"text": {
"content": "【WXAuto Center 告警】\n事件类型: 微信掉线\n节点: wx1 (微信1)\n状态: offline\n时间: 2026-04-05 10:00:00"
}
}
Bark 格式：
{
"title": "WXAuto告警 - 微信掉线",
"body": "wx1\n状态: offline\n时间: 2026-04-05 10:00:00",
"icon": "https://..."
}
5. 健康检测流程
5.1 流程图
is_node_healthy(node_id) 调用
│
▼
┌─────────────────────────────────────────────────────────────┐
│ check_node_status(node_id) │
│ 调用 GET /health 检测 API 可用性 │
└─────────────────────────────────────────────────────────────┘
│
▼
API 状态检查
│
├──► API 不可用 → 返回 (False, "API status: {status}")
│
▼ (API 可用)
┌─────────────────────────────────────────────────────────────┐
│ /api/wechat/initialize │
│ 调用 POST /api/wechat/initialize 初始化微信 │
└─────────────────────────────────────────────────────────────┘
│
▼
解析返回状态 (code, message, status)
│
├──► code != 0?
│ │
│ ├──► "无效"/"1400"/"拒绝访问"
│ │ │
│ │ ▼
│ │ 返回 (False, "WeChat window invalid")
│ │
│ └──► 其他错误消息
│ │
│ ▼
│ 返回 (False, "WeChat error: {message}")
│
├──► status not in ["connected", "online"]?
│ │
│ └──► 是 → 返回 (False, "WeChat status: {status}")
│
└──► 其他情况
│
▼
返回 (True, "OK")
5.2 健康检测判断逻辑
async def is_node_healthy(node_id: str) -> tuple[bool, str]:
# 1. 检查 API 状态
api_status = await self.check_node_status(node_id)
if api_status != NodeStatus.ACTIVE:
return False, f"API status: {api_status}"
# 2. 调用 /api/wechat/initialize 检测微信
init_result = await self.call_node_api(node_id, "/api/wechat/initialize", method="POST")
# 3. 解析返回状态
if not init_result.get("success"):
return False, f"WeChat check failed: {init_result.get('error')}"
wx_code = init_result.get("code") or init_result.get("data", {}).get("code")
wx_status = init_result.get("data", {}).get("data", {}).get("status")
if wx_code != 0:
return False, "WeChat error: ..."
if wx_status not in ["connected", "online"]:
return False, f"WeChat status: {wx_status}"
return True, "OK"
6. 微信状态机
6.1 状态定义
| 状态 | 说明 | 可转换状态 |
|---|---|---|
| online | 微信正常在线（默认/成功状态） | offline |
| offline | 微信掉线或不可用 | online |
6.2 状态转换图
┌──────────────┐
│ online │
│ (默认/成功) │
└──────┬───────┘
│
发送消息失败
或微信掉线检测
│
▼
┌──────────────┐
│ offline │
└──────┬───────┘
│
回调重置成功
(文件传输助手检测)
│
▼
┌──────────────┐
│ online │
└──────────────┘
6.3 状态转换场景
| 场景 | 原状态 | 新状态 | 触发条件 |
|---|---|---|---|
| 消息发送成功 | online | online | code == 0 |
| 消息发送失败 | online | offline | code != 0 |
| 微信掉线 | online | offline | 监控检测到异常 |
| 回调重置成功 | offline | online | 检测消息发送成功 |
| 回调重置失败 | offline | offline | 检测消息发送失败 |
7. 日志发布订阅流程
7.1 流程图
业务操作调用
│
├──► log_service.info(message, source)
├──► log_service.warning(message, source)
├──► log_service.error(message, source)
└──► log_service.success(message, source)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LogEntry 创建 │
│ {timestamp, level, source, message} │
└─────────────────────────────────────────────────────────────┘
│
├──► 存入 deque (本地缓存，最多 500 条)
│
└──► 推送到 SSE Queue
│
▼
所有订阅者收到消息
│
▼
unsubscribe() 取消订阅
7.2 SSE 订阅示例
// 前端订阅日志流
const eventSource = new EventSource('/api/v1/logs/stream');
eventSource.onmessage = (event) => {
const logEntry = JSON.parse(event.data);
console.log(`[${logEntry.level}] ${logEntry.message}`);
};
eventSource.onerror = (error) => {
console.error('SSE Error:', error);
eventSource.close();
};
7.3 日志级别
| 级别 | 说明 | 使用场景 |
|---|---|---|
| INFO | 信息 | 一般操作日志 |
| WARNING | 警告 | 异常但可恢复 |
| ERROR | 错误 | 操作失败 |
| SUCCESS | 成功 | 操作成功确认 |
8. 批量操作流程
8.1 广播消息流程
广播请求
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /api/v1/messages/broadcast │
│ 请求体: {node_ids, who, msg, msg_type} │
└─────────────────────────────────────────────────────────────┘
│
▼
node_ids 为空?
│
├──► 是 → 获取所有已启用节点
│
▼ (否)
使用指定的 node_ids
│
▼
对每个节点并行发送消息
│
├──► 节点1 → send_message() → 结果1
├──► 节点2 → send_message() → 结果2
└──► 节点N → send_message() → 结果N
│
▼
汇总结果
│
▼
返回批量结果
8.2 批量发送流程
批量请求
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /api/v1/messages/batch │
│ 请求体: {messages: [{node_id, who, msg, msg_type}, ...]} │
└─────────────────────────────────────────────────────────────┘
│
▼
验证消息列表
│
▼
对每条消息并行发送
│
├──► 消息1 → send_message() → 结果1
├──► 消息2 → send_message() → 结果2
└──► 消息N → send_message() → 结果N
│
▼
汇总结果
│
▼
返回批量结果
9. 插件执行流程
9.1 外部触发流程
外部请求
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /api/v1/external/trigger │
│ 请求体: {source, event, data, auto_send, target, node_id} │
└─────────────────────────────────────────────────────────────┘
│
▼
获取插件
│
▼
执行插件
│
├──► plugin.execute(event, data)
│
▼
auto_send = true?
│
├──► 是 → 发送消息到 target
│ │
│ ▼
│ 返回 {plugin_result, send_result}
│
└──► 否 → 返回 {plugin_result}
10. 完整状态流转图
┌─────────────────────────────────────┐
│ 系统启动 │
│ 节点创建 (wechat_status=online) │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 正常运行 │
│ wechat_status=online │
└─────────────────┬───────────────────┘
│
┌─────────────────┴─────────────────┐
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ 消息发送成功 │ │ 消息发送失败 │
│ wechat_status= │ │ wechat_status= │
│ online │ │ offline │
└───────────────────────┘ └───────────┬───────────┘
│
▼
┌───────────────────────┐
│ 调用回调重置接口 │
│ POST /callback/node/ │
│ reset │
└───────────┬───────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ 重置成功 │ │ 重置失败 │
│ 发送检测消息成功 │ │ 发送检测消息失败 │
│ wechat_status= │ │ wechat_status= │
│ online │ │ offline │
└───────────────────────┘ └───────────────────────┘
│
▼
┌───────────────────────┐
│ 触发 Webhook 告警 │
│ wechat_offline │
└───────────────────────┘
更新日志
| 日期 | 更新内容 |
|---|---|
| 2026-04-05 | 创建 FLOWS.md 业务流程文档 |
| 2026-04-05 | 添加消息发送流程图 |
| 2026-04-05 | 添加回调重置流程图 |
| 2026-04-05 | 添加监控告警流程图 |
| 2026-04-05 | 添加健康检测流程图 |
| 2026-04-05 | 添加微信状态机说明 |
| 2026-04-05 | 添加日志发布订阅流程图 |