modify: sophon 视频文件上传、告警接口

README.md

@@ -206,6 +206,89 @@ summary = "Add via MQTT"
 params = ["a: float", "b: float"]
 ```
 
+### 两种路由注册方式
+
+本项目支持两种路由注册方式，根据场景选用：
+
+#### 方式一：TOML 动态路由（标准 JSON 端点）
+
+通过 `config/workers/<插件>/*.toml` 定义 `[GET]` / `[POST]` 节，网关自动生成 FastAPI 路由。
+适用于参数和响应可被 Pydantic 模型描述的标准 JSON 接口。
+
+- 路由生成流程：`TOML 配置 → 自动生成 Pydantic 模型 → 注册 FastAPI 路由`
+- 底层 RPC：`FastAPI 路由 → WorkerManager.call() → Zenoh Query → Worker @rpc_method → 响应`
+
+```toml
+# config/workers/example/add.toml
+[GET]
+summary = "加法"
+params = ["a: float", "b: float"]
+[GET.response_model]
+result = { type = "float", required = true }
+```
+
+#### 方式二：插件自定义路由（特殊端点）
+
+当端点无法用 TOML 描述时（如 `multipart/form-data` 文件上传），插件可在模块顶层暴露
+一个 `APIRouter` 实例，网关在 `load_workers()` 阶段自动发现并注册（无需修改网关代码）。
+
+**约定**：插件模块（`__init__.py`）需导入并暴露一个名为 `router` 的 `APIRouter` 实例：
+
+```python
+# src/plugins/<name>/__init__.py
+from .routes import router  # 暴露给网关自动发现
+```
+
+```python
+# src/plugins/<name>/routes.py
+from fastapi import APIRouter, UploadFile, File, Form
+
+router = APIRouter(prefix="/<prefix>", tags=["<worker_type>"])
+
+@router.post("/upload")
+async def upload(
+    file: UploadFile = File(...),
+    param1: str = Form(...),
+):
+    ...
+    return {"result": "ok"}
+```
+
+- 全局前缀（如 `/api/v1`）由网关自动注入，插件无需关心
+- tags 应与 TOML 自动生成的端点保持一致（使用 worker_type）
+- TOML 配置中对应端点应设 `internal = true`，避免重复注册
+
+### HTTP / MQTT 调用路径
+
+同一端点通过**不同通道**到达 Worker 的路径对比：
+
+| 通道     | 调用路径                                                                                | 适用场景                       |
+| -------- | --------------------------------------------------------------------------------------- | ------------------------------ |
+| **HTTP** | `客户端 → FastAPI 路由 → WorkerManager.call() → Zenoh Query → Worker`                   | REST API、Web 前端、文件上传   |
+| **MQTT** | `MQTT 客户端 → 内嵌 Broker → MQTT Bridge → WorkerManager.call() → Zenoh Query → Worker` | IoT 设备上报、心跳、低带宽环境 |
+
+HTTP 和 MQTT 最终都通过 Zenoh RPC 调用 Worker 的 `@rpc_method` 处理函数，业务逻辑完全共享。
+
+```
+                  ┌──────────────────────────────┐
+                  │      WorkerManager           │
+                  │   (负载均衡 / 超时重试)        │
+                  └──────────┬───────────────────┘
+                             │ Zenoh Query
+                  ┌──────────▼───────────────────┐
+                  │      Worker 副本池            │
+                  │  ┌─────┐ ┌─────┐ ┌─────┐     │
+                  │  │  W1 │ │  W2 │ │  W3 │     │
+                  │  └──┬──┘ └──┬──┘ └──┬──┘     │
+                  │     │       │       │         │
+                  │  @rpc_method 处理函数           │
+                  └────────────────────────────────┘
+         HTTP 请求到达 ▲              ▲ MQTT 消息到达
+              ┌───────┘              └───────┐
+     FastAPI 路由（TOML 自动生成）    MQTT Bridge
+     插件自定义路由（router 约定）     (chongming/+/+)
+```
+
 ### 添加新 Worker 插件
 
 1. 创建 `src/plugins/<name>/` — `__init__.py`, `global_var.py`, `router/`, `models/`
@@ -245,11 +328,12 @@ uv pip install -e utils/<name>            # 安装/更新工具包子包
 
 ## 内置插件
 
-| 插件        | HTTP 前缀 | MQTT 主题前缀 | 说明                                 |
-| ----------- | --------- | ------------- | ------------------------------------ |
-| **auth**    | `/auth`   | `auth.*`      | 注册、登录、JWT 鉴权、个人信息、改密 |
-| **doubao**  | `/doubao` | `doubao.*`    | 火山引擎豆包视觉理解模型             |
-| **example** | `/calc`   | `example.*`   | 四则运算 + 访问计数 + MQTT 心跳示例  |
+| 插件                     | HTTP 前缀 | MQTT 主题前缀            | 说明                                 |
+| ------------------------ | --------- | ------------------------ | ------------------------------------ |
+| **auth**                 | `/auth`   | `auth.*`                 | 注册、登录、JWT 鉴权、个人信息、改密 |
+| **doubao**               | `/doubao` | `doubao.*`               | 火山引擎豆包视觉理解模型             |
+| **example**              | `/calc`   | `example.*`              | 四则运算 + 访问计数 + MQTT 心跳示例  |
+| **aibox_sophon_adapter** | `/aibox`  | `aibox_sophon_adapter.*` | AI Box 设备心跳适配 + 视频上传       |
 
 ---