wxauto_api/doc/wxauto_center/MODULES.md

WXAuto Center 模块索引文档

1. 模块概览

WXAuto Center 采用分层架构，主要分为以下模块：

层级	模块	路径	职责
接入层	API Routes	api/	处理 HTTP 请求，提供 RESTful 接口
业务逻辑层	Services	services/	核心业务逻辑处理
公共工具层	Utils	utils/	公共函数和依赖注入
插件系统	Plugins	plugins/	扩展功能插件
配置层	Config	config.py	系统配置管理
入口	Main	main.py	FastAPI 应用入口

---

2. 模块详细说明

2.1 接入层 (API Layer)

api/nodes.py - 节点管理 API

文件路径：nodes.py

职责：

• 节点的增删改查 (CRUD)
• 节点状态检测
• 微信初始化
• 节点启用/禁用
• 获取好友列表、群列表、聊天消息

主要端点：

方法	路径	说明
GET	/nodes	获取所有节点
GET	/nodes/{node_id}	获取指定节点
POST	/nodes	添加节点
PUT	/nodes/{node_id}	更新节点
DELETE	/nodes/{node_id}	删除节点
POST	/nodes/{node_id}/enable	启用节点
POST	/nodes/{node_id}/disable	禁用节点
GET	/nodes/{node_id}/status	检查节点状态
GET	/nodes/{node_id}/wechat/status	获取微信状态
POST	/nodes/{node_id}/wechat/initialize	初始化微信

依赖：services.node_manager, utils.require_api_key

节点标识说明：所有接口使用 node_id 作为节点唯一标识。

---

api/messages.py - 消息管理 API

文件路径：messages.py

职责：

• 发送消息
• 发送群消息
• 批量发送消息
• 发送模板消息
• 获取消息历史

主要端点：

方法	路径	说明
POST	/messages/send	发送消息
POST	/messages/send_group	发送群消息
POST	/messages/batch	批量发送
POST	/messages/template/{node_id}/{who}	发送模板消息
GET	/messages/history/{node_id}/{chat_name}	获取消息历史

依赖：services.node_manager, utils.require_api_key, utils.check_node_health

说明：已移除广播功能。

---

api/external.py - 外部扩展 API

文件路径：external.py

职责：

• 供外部系统调用的接口
• 外部消息发送
• 数据处理触发
• 插件执行
• AI 消息处理
• Webhook 接收

主要端点：

方法	路径	说明
POST	/external/send	外部接口-发送消息
POST	/external/trigger	外部接口-触发数据处理
POST	/external/plugin/execute	外部接口-执行插件
GET	/external/plugins	外部接口-获取插件列表
GET	/external/nodes	外部接口-获取可用节点
POST	/external/ai/process	外部接口-AI处理消息
POST	/external/webhook/{event}	外部接口-Webhook接收

认证方式：X-ExternalKey Header

依赖：services.node_manager, plugins.base.PluginRegistry, utils.require_external_key

---

api/plugins.py - 插件管理 API

文件路径：plugins.py

职责：

• 插件注册和管理
• 插件启用/禁用
• 插件配置更新
• 按类型获取插件

主要端点：

方法	路径	说明
GET	/plugins	获取所有插件
GET	/plugins/{plugin_name}	获取插件详情
POST	/plugins/{plugin_name}/enable	启用插件
POST	/plugins/{plugin_name}/disable	禁用插件
PUT	/plugins/{plugin_name}/config	更新插件配置
POST	/plugins/{plugin_name}/execute	执行插件
GET	/plugins/type/{plugin_type}	按类型获取插件

依赖：plugins.base.PluginRegistry, utils.require_api_key

---

api/callback.py - 回调接口 API

文件路径：callback.py

职责：

• 外部节点回调
• 节点微信状态重置
• 节点微信状态检测
• 节点状态查询

主要端点：

方法	路径	说明
POST	/callback/node/reset	重置节点微信状态
POST	/callback/node/check	检测节点微信状态
GET	/callback/node/{node_id}/status	获取节点回调状态

业务流程：

1. 发送消息 → 失败 → wechat_status = offline
2. 回调重置接口 → 发送检测消息 → 成功 → wechat_status = online
3. 监控服务检测状态变化 → 触发Webhook告警

依赖：services.node_manager, services.log_service, utils.require_api_key

---

2.2 业务逻辑层 (Service Layer)

services/node_manager.py - 节点管理服务

文件路径：node_manager.py

职责：

• 节点注册和注销
• 节点通信管理
• API 调用封装
• 消息发送
• 节点状态检测

核心类：

类名	说明
NodeStatus	节点状态枚举 (ACTIVE, INACTIVE, ERROR)
Node	节点数据模型（包含 node_id 和 name）
NodeManager	节点管理服务类

主要方法：

方法	说明
add_node()	添加节点
remove_node(node_id)	删除节点
get_node(node_id)	获取节点
get_all_nodes()	获取所有节点
get_enabled_nodes()	获取已启用节点
check_node_status(node_id)	检测节点状态
is_node_healthy(node_id)	判断节点是否健康
call_node_api()	调用节点 API
send_message(node_id, who, msg, msg_type)	发送消息
send_message_to_group(node_id, group_name, msg, msg_type)	发送群消息

内部方法：

方法	说明
_send_message_internal()	发送消息的内部方法 (复用逻辑)

依赖：services.log_service

---

services/monitor_service.py - 监控服务

文件路径：monitor_service.py

职责：

• 定时检测节点状态
• 检测 API 状态变化
• 检测微信状态变化
• 触发 Webhook 告警

主要方法：

方法	说明
start()	启动监控服务
stop()	停止监控服务
get_last_status()	获取节点最后状态
get_all_status()	获取所有节点状态

内部方法：

方法	说明
_monitor_loop()	监控主循环
_check_all_nodes()	检测所有节点
_check_node()	检测单个节点
_send_webhook()	发送 Webhook 通知

依赖：config.get_settings, services.node_manager, services.log_service

---

services/log_service.py - 日志服务

文件路径：log_service.py

职责：

• 日志记录
• 日志缓存 (deque，最多 500 条)
• SSE 实时推送
• 发布订阅模式
• Redis 缓存支持
• 文件持久化 (logs/app.log)

日志级别：INFO, WARNING, ERROR, SUCCESS

主要方法：

方法	说明
info()	记录 INFO 日志
warning()	记录 WARNING 日志
error()	记录 ERROR 日志
success()	记录 SUCCESS 日志
subscribe()	订阅日志流
unsubscribe()	取消订阅
get_recent_logs()	获取最近日志
get_all_logs()	获取所有日志

---

services/queue_service.py - 消息队列服务

文件路径：queue_service.py

职责：

• 消息队列管理
• Redis 后端支持（可选）
• 本地队列回退
• 异步任务处理

队列名称：

队列名	说明
MESSAGE_SEND	消息发送队列
MESSAGE_BROADCAST	消息广播队列（已废弃）

主要方法：

方法	说明
enqueue()	入队操作
dequeue()	出队操作（异步）
get_queue_length()	获取队列长度
start_worker()	启动工作进程
stop_worker()	停止工作进程

依赖：Redis (可选)，若 Redis 不可用则使用本地 asyncio.Queue

---

2.3 公共工具层 (Utils Layer)

utils/common.py - 公共函数

文件路径：common.py

职责：

• API Key 验证依赖 (require_api_key)
• External Key 验证依赖 (require_external_key)

主要函数：

函数名	说明
require_api_key	API Key 验证依赖，用于 X-API-Key Header
require_external_key	External Key 验证依赖，用于 X-ExternalKey Header

使用示例：

from utils import require_api_key

@router.post("/endpoint")
async def endpoint(_=Depends(require_api_key)):
    # 处理请求
    pass

---

utils/helpers.py - 业务辅助函数

文件路径：helpers.py

职责：

• 节点健康检查
• 响应构建
• 结果解析

主要函数：

函数名	说明
check_node_health()	检查节点健康状态，不健康则抛 503 异常
build_success_response()	构建成功响应
build_error_response()	构建错误响应
parse_node_result()	解析节点 API 调用结果

---

2.4 插件系统 (Plugin Layer)

plugins/base.py - 插件基类

文件路径：base.py

职责：

• 定义插件接口
• 插件注册表

核心类：

类名	说明
PluginType	插件类型枚举
PluginBase	插件基类
MessageHandlerPlugin	消息处理插件基类
DataSourcePlugin	数据源插件基类
ActionTriggerPlugin	动作触发插件基类
AIAgentPlugin	AI 智能体插件基类
PluginRegistry	插件注册表

PluginType 枚举值：

• MESSAGE_HANDLER = "message_handler"
• DATA_SOURCE = "data_source"
• ACTION_TRIGGER = "action_trigger"
• AI_AGENT = "ai_agent"
• CUSTOM = "custom"

---

plugins/builtin.py - 内置插件

文件路径：builtin.py

内置插件：

插件名	类名	说明
http_data_source	HTTPDataSourcePlugin	HTTP 数据源插件，从外部 API 获取数据
database_query	DatabaseQueryPlugin	数据库查询插件 (预留)
webhook_trigger	WebhookTriggerPlugin	Webhook 触发器
simple_ai_agent	SimpleAIAgentPlugin	简单 AI 智能体

注册函数：register_builtin_plugins()

---

2.5 配置层 (Config Layer)

config.py - 配置管理

文件路径：config.py

职责：

• 系统配置管理
• 配置文件读写
• 多环境支持

核心配置类：

类名	说明
NodeConfig	节点配置
PluginConfig	插件配置
WebhookConfig	Webhook 配置
MonitorConfig	监控配置
Settings	应用设置 (继承 BaseSettings)
ConfigManager	配置管理器

主要函数：

函数名	说明
get_settings()	获取全局设置单例
update_settings()	更新设置
load_config_from_file()	从文件加载配置
save_config_to_file()	保存配置到文件

ConfigManager 方法：

方法	说明
get_node()	获取节点配置
get_all_nodes()	获取所有节点配置
get_enabled_nodes()	获取已启用节点配置
add_node()	添加节点配置
update_node()	更新节点配置
remove_node()	删除节点配置
save_config()	保存配置
load_config()	加载配置

---

2.6 入口 (Main)

main.py - 应用入口

文件路径：main.py

职责：

• FastAPI 应用初始化
• 中间件配置
• 路由注册
• 启动/关闭事件处理
• 配置管理 API
• 监控状态 API
• 日志流 API

---

3. 模块依赖关系

                    ┌─────────────┐
                    │   main.py  │
                    └──────┬──────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
    ┌─────────┐       ┌─────────┐       ┌─────────┐
    │ config  │       │  api/*  │       │ services│
    └────┬────┘       └────┬────┘       └────┬────┘
         │                 │                 │
         │                 ▼                 ▼
         │           ┌───────────┐      ┌─────────┐
         │           │  utils/* │      │plugins/*│
         │           └───────────┘      └─────────┘
         │                 │                 │
         └─────────────────┼─────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  external   │
                    │ (WXAuto-HTTP │
                    │    -API)     │
                    └─────────────┘

依赖详解：

模块	被依赖	依赖
main.py	-	config, api, services, plugins
config.py	api, services, main	pydantic, pydantic_settings
api/*	main	services, plugins, utils, config
services/*	api	config, log_service
utils/*	api	config
plugins/*	api, main	httpx
log_service	services	-

---

4. 代码导览

4.1 新增代码路径

重构后新增的公共模块：

文件	说明
utils/__init__.py	工具模块导出
utils/common.py	API Key 验证依赖
utils/helpers.py	业务辅助函数

4.2 重构变更

删除的重复代码

以下文件中删除了重复定义的 require_api_key 函数：

• api/nodes.py - 现在从 utils 导入
• api/messages.py - 现在从 utils 导入
• api/external.py - 现在从 utils 导入
• api/plugins.py - 现在从 utils 导入
• api/callback.py - 现在从 utils 导入

重构的方法

文件	原方法	新方法
services/node_manager.py	send_message() 和 send_message_to_group() 重复代码	新增 _send_message_internal() 内部方法
api/callback.py	reset_node_wechat_status() 和 check_node_wechat_status() 重复逻辑	新增 _check_wechat_and_update_status() 公共函数

4.3 代码审计指南

审计要点

1. API Key 验证

   • 所有 API 端点必须使用 Depends(require_api_key) 或 Depends(require_external_key)
   • 检查 X-API-Key 和 X-ExternalKey 是否正确使用

2. 节点健康检查

   • 发送消息前必须调用 check_node_health()
   • 使用 utils.check_node_health 而非直接调用 node_manager.is_node_healthy

3. 配置保存

   • 修改节点配置后必须调用 save_nodes_config() 保存
   • 修改全局配置后必须调用 save_config_to_file() 保存

4. 错误处理

   • 使用 build_success_response() 和 build_error_response() 构建响应
   • 节点不存在时抛出 HTTPException(status_code=404)

5. 异步处理

   • 所有 node_manager 方法都是异步的，使用 await
   • API 端点需要 async def

---

5. 模块索引

5.1 文件快速查找

功能	文件路径
API Key 验证	utils/common.py
节点健康检查	utils/helpers.py
节点管理	services/node_manager.py
状态监控	services/monitor_service.py
日志服务	services/log_service.py
节点 API	api/nodes.py
消息 API	api/messages.py
外部 API	api/external.py
插件 API	api/plugins.py
回调 API	api/callback.py
插件基类	plugins/base.py
内置插件	plugins/builtin.py
配置管理	config.py
应用入口	main.py

5.2 类和函数查找

类/函数	文件	行号
NodeStatus	node_manager.py	L15
Node	node_manager.py	L21
NodeManager	node_manager.py	L46
MonitorService	monitor_service.py	L18
LogService	log_service.py	L14
PluginBase	base.py	L21
PluginRegistry	base.py	L92
require_api_key	common.py	L10
require_external_key	common.py	L30
check_node_health	helpers.py	L20
ConfigManager	config.py	L148

---

6. 更新日志

日期	更新内容
2026-04-05	更新 API 路径，将 node_name 替换为 node_id
2026-04-05	重构代码，新增 utils 模块，抽取公共函数
2026-04-05	新增 MODULES.md 模块索引文档
2026-04-05	更新 API.md，添加回调接口文档
2026-04-05	更新 ARCHITECTURE.md，添加回调流程图和微信状态机
2026-04-05	新增 QueueService 消息队列服务模块
2026-04-05	更新 LogService 支持 Redis 缓存和文件持久化
2026-04-05	移除广播功能相关文档