租户开发接入文档

1. 文档说明

本文档从租户视角介绍：

平台架构与调用流程
设备级 / 租户级两种接入模式
HTTP / MQTT 接口与文档入口
租户 HTTP 回调转发包装协议

协议优先级说明：设备消息体字段、主题定义、错误码请以设备通信协议（最新版）为最新标准。

2. 租户视角平台架构

flowchart LR
    U[终端用户] --> A[租户 App]
    A --> TP[租户平台]
    A --> CP[云打印平台]
    TP --> CP[云打印平台]

    CP --> AI1[文生图模块]
    CP --> AI2[LLM 模块]
    CP --> MQ[MQTT 服务]
    CP --> ASR[ASR 服务]

    AI1 -.可按租户文生图标准接入.- TTI[租户文生图服务]
    AI2 -.OpenAPI兼容可接入.- LLM[租户LLM服务]
    ASR -.可接入租户提供的ASR平台.- TASR[租户 ASR 平台]

    D[设备] <--> CP
    D <--> MQ
    D <--> ASR

说明：

租户 App 只能对接租户平台或云打印平台，不直接与设备通信。
设备直接与云打印平台及其提供的 MQTT、ASR 服务交互，不直接对接租户 App、租户平台或其他租户侧基础设施。
ASR 能力由云打印平台内 ASR 服务承接，并支持接入租户提供的 ASR 平台。

3. 两种接入模式与优势

模式	核心特点	主要优势
设备级接入	App 直接持设备临时 Token 调用云平台	平台对接压力小、交互链路短、响应快、问题定位简单
租户级接入	租户后端持租户 Token 调用平台完整接口	接口能力丰富，便于统一资源管理、扩展业务能力、集中治理

4. 设备级接入流程

sequenceDiagram
    autonumber
    participant App as 租户App
    participant Dev as 设备
    participant TP as 租户平台
    participant CP as 云打印平台

    App->>TP: 提交 SN 与绑定申请

    alt 需要设备验证码校验
      TP->>CP: 推送设备验证码
      CP->>Dev: 设备打印验证码
      App->>TP: 提交 SN + 验证码
    else 无需设备验证码
      TP->>CP: 直接发起绑定
    end

    TP->>CP: 绑定设备，获取 appAuthCode
    CP-->>TP: 返回 appAuthCode
    TP->>CP: 使用 SN + appAuthCode 换取设备临时 token
    CP-->>TP: 返回 token + expiresIn
    TP-->>App: 返回 token + expiresIn

    App->>CP: 使用设备 token 调用接口（创建任务等）
    App->>CP: 使用设备 token 监听设备 MQTT 主题

4.1 设备级核心 HTTP 接口

设备绑定：
- POST /api/v1/public/device/bind
- Swagger: 设备绑定接口
设备登录（获取临时 Token）：
- POST /api/v1/public/device/login
- Swagger: 设备登录接口
设备级创建打印任务：
- POST /api/v1/device-app/print-jobs
- Swagger: 设备级创建打印任务接口
设备级状态查询：
- GET /api/v1/device-app/device/state
- Swagger: 设备状态查询接口

4.2 设备级 MQTT

App 作为设备应用客户端订阅设备主题（监听状态、回执）。
常用主题：
- devices/{tenantCode}/{userName}/{sn}/up/state
- devices/{tenantCode}/{userName}/{sn}/up/print/ack
- devices/{tenantCode}/{userName}/{sn}/up/upgrade/ack
- devices/{tenantCode}/{userName}/{sn}/up/control/ack

5. 租户级接入流程

sequenceDiagram
    autonumber
    participant TP as 租户平台
    participant CP as 云打印平台

    TP->>CP: APIKey + Secret 获取租户Token
    CP-->>TP: 返回租户Token

    TP->>CP: 上传文件、创建任务、查询任务、控制队列
    CP-->>TP: 返回业务结果

    par 消息接收（HTTP）
      CP-->>TP: 按租户配置回调设备消息
    and 消息接收（MQTT）
      TP-->>CP: 订阅 device/{tenantCode}/#
      CP-->>TP: 按租户转发消息流
    end

5.1 租户级核心 HTTP 接口

租户鉴权：
- POST /api/v1/dealer-api-auth
- Swagger: 租户鉴权接口
租户上传凭证：
- POST /api/v1/files/upload-token
- Swagger: 上传凭证接口
租户创建打印任务（你给的示例）：
- POST /api/v1/print-jobs
- Swagger: 创建打印任务接口
租户任务详情：
- GET /api/v1/print-jobs/{id}
- Swagger: 打印任务详情接口
租户任务列表：
- GET /api/v1/print-jobs
- Swagger: 打印任务列表接口
租户数据转发配置：
- PUT /api/v1/dealers/current/data-forward
- Swagger: 租户数据转发配置接口

6. 租户 HTTP 回调包装协议

回调方式：POST {endpointUrl}，请求体统一 JSON，详细内容设备消息体字段、主题定义、错误码请以设备通信协议（最新版）为最新标准。。

6.1 统一外层包装

{
  "messageType": "up/state",
  "deviceId": "SN123456",
  "tenantCode": "tenant_a",
  "username": "owner_user",
  "data": {}
}

字段说明：

messageType: 主题业务类型
deviceId: 设备 SN
tenantCode: 租户编码
username: 设备归属用户名（主题中的 userName）
data: 设备协议消息体（详见设备通信协议（最新版））

6.2 全主题映射

主题	messageType	数据方向	主要用途	data 内容来源
`devices/{tenantCode}/{userName}/{sn}/up/state`	`/up/state`	设备 -> 云平台	上报设备状态（电量、纸张、网络、固件等）	设备状态上报消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/up/print/ack`	`/up/print/ack`	设备 -> 云平台	上报打印任务确认、进度、成功/失败回执	打印回执消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/up/upgrade/ack`	`/up/upgrade/ack`	设备 -> 云平台	上报升级任务确认、下载/升级进度、成功/失败回执	升级回执消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/up/control/ack`	`/up/control/ack`	设备 -> 云平台	上报控制指令执行结果	控制回执消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/up/event`	`/up/event`	设备 -> 云平台	上报设备事件（如停止打印）	设备事件消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/up/pull`	`/up/pull`	设备 -> 云平台	主动拉取打印资源、文生图资源或功能列表	Pull 请求消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/down/print`	`/down/print`	云平台 -> 设备	下发打印任务与资源清单	打印任务下发消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/down/upgrade`	`/down/upgrade`	云平台 -> 设备	下发固件升级任务	升级任务下发消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/down/control`	`/down/control`	云平台 -> 设备	下发设备控制指令（重启/关机/清缓存等）	控制指令下发消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/down/pull/ack`	`/down/pull/ack`	云平台 -> 设备	回复 Pull 请求“无可用任务”等结果	Pull Ack 消息体（按 `device-protocol.md`）
`devices/{tenantCode}/{userName}/{sn}/down/resource`	`/down/resource`	云平台 -> 设备	返回功能列表或资源请求失败信息	资源响应消息体（按 `device-protocol.md`）

6.3 上下线事件

设备上线

{
  "messageType": "client_connected",
  "deviceId": "SN123456",
  "tenantCode": "tenant_a",
  "userName": "owner_user",
  "sourceUsername": "tenant_a|owner_user|SN123456",
  "data": {
    "event": "client_connected",
    "clientid": "SN123456|0.1",
    "username": "tenant_a|owner_user|SN123456",
    "peername": "10.0.0.10:53721",
    "sockname": "10.0.0.1:1883",
    "connected_at": 1740000000,
    "timestamp": 1740000000
  }
}

设备下线

{
  "messageType": "client_disconnected",
  "deviceId": "SN123456",
  "tenantCode": "tenant_a",
  "userName": "owner_user",
  "sourceUsername": "tenant_a|owner_user|SN123456",
  "data": {
    "event": "client_disconnected",
    "clientid": "SN123456|0.1",
    "username": "tenant_a|owner_user|SN123456",
    "reason": "normal",
    "peername": "10.0.0.10:53721",
    "connected_at": 1740000000,
    "disconnected_at": 1740000300,
    "timestamp": 1740000300
  }
}

6.4 各主题 data 内容示例

以下示例已按设备通信协议（最新版）对齐。具体字段、约束、枚举、错误码如有变更，请始终以该协议文档为准。

1) `/up/state`

{
  "msgId": "a1b2c3d4e5f6789012345678901234ab", // 消息唯一ID，32字符
  "ts": 1724040060000, // 消息时间戳（13位毫秒）
  "rssi": -58, // WiFi 信号强度（dBm）
  "battery": 90, // 电池电量百分比（0~100）
  "paper": 1, // 纸张状态：0=无纸，1=有纸
  "paperType": "roll", // 纸张类型：fold/roll/gap/hole/tattoo
  "errCode": [], // 错误码数组：空数组表示正常，可同时上报多个错误码
  "temperature": 35.2, // 可选：设备温度（摄氏度）
  "humidity": 45, // 可选：设备湿度（0~100）
  "ipAddress": "192.168.1.25", // 可选：设备IP地址
  "bluetoothMac": "00:1A:7D:DA:71:13", // 可选：蓝牙MAC地址
  "imei": "865123456789012", // 可选：4G模块IMEI号（15位数字）
  "iccid": "89860123456789012345", // 可选：SIM卡ICCID号（18-22位数字）
  "signalStrength": -75, // 可选：4G信号强度（dBm）
  "networkType": "4G", // 可选：网络类型（2G/3G/4G/5G）
  "printCount": 12345, // 可选：累计打印张数
  "avgLatency": 150, // 可选：平均延时（毫秒）
  "packetLossRate": 2, // 可选：丢包率（0~100，如2表示2%）
  "charging": false, // 可选：是否正在充电
  "sleepTime": 10, // 可选：休眠时间（分钟）
  "firmware": [ // 固件版本列表
    {
      "firmwareType": "cloud", // 固件类型
      "firmwareVersion": "1.2.3", // 固件版本号
      "nn": "NN-001" // 模组NN号
    },
    {
      "firmwareType": "printer", // 固件类型
      "firmwareVersion": "3.4.5", // 固件版本号
      "nn": "NN-002" // 打印机NN号
    },
    {
      "firmwareType": "bluetooth", // 固件类型
      "firmwareVersion": "0.9.8" // 固件版本号
    }
  ]
}

2) `/up/print/ack`

{
  "msgId": "b2c3d4e5f67890a1b2c3d4e5f67890a1", // 消息唯一ID，32字符
  "jobId": "92ef08872ff906876071478274eec57b", // 打印任务ID
  "ackOriginalMsgId": "a1b2c3d4e5f6789012345678901234ab", // 原始下发消息的msgId
  "status": "confirm", // 任务状态：confirm/printing/success/failed
  "seqs": [1, 2, 3, 4, 5], // 确认的资源序号数组
  "errCode": [], // 错误码数组，空数组表示成功
  "msg": "ok", // 错误描述信息或状态说明
  "ts": 1724040088000 // 消息时间戳（13位毫秒）
}

3) `/up/upgrade/ack`

{
  "msgId": "d4e5f6789012a3b4c5d6e7f89012a3b4", // 消息唯一ID，32字符
  "deviceUpgradeId": "92ef08872ff906876071478274eec57b", // 设备升级任务ID
  "ackOriginalMsgId": "原始下发消息的msgId", // 原始下发消息的msgId
  "status": "upgrading", // 升级状态：confirm/downloading/upgrading/success/failed
  "errCode": [], // 错误码数组，空数组表示成功
  "msg": "ok", // 错误描述信息或状态说明
  "ts": 1724041088000 // 消息时间戳（13位毫秒）
}

4) `/up/control/ack`

{
  "msgId": "g5h6i7j890k1l2m3n4o5p6q789r0s1t2", // 消息唯一ID，32字符
  "controlId": "a351eff1b614d0c1f64227d0c4b28c99", // 控制指令ID
  "ackOriginalMsgId": "原始下发消息的msgId", // 原始下发消息的msgId
  "status": "confirm", // 执行状态：confirm/success/failed
  "errCode": [], // 错误码数组，空数组表示成功
  "msg": "ok", // 错误描述信息或状态说明
  "ts": 1724042088000 // 消息时间戳（13位毫秒）
}

5) `/up/event`

{
  "msgId": "h7i8j9k012l3m4n5o6p7q8r901s2t3u4", // 消息唯一ID，32字符
  "eventType": "stop_print", // 事件类型
  "eventParams": { // 事件参数（可选）
    "reason": "user_action" // 事件原因或其他参数
  },
  "ts": 1724043088000 // 消息时间戳（13位毫秒）
}

6) `/up/pull`

{
  "msgId": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6", // 消息唯一ID，32字符
  "type": "print", // 资源类型：print/text_to_image/feature_list
  "params": { // 类型参数对象
    "jobId": "", // type=print时：空=请求新任务，非空=请求该任务后续资源
    "seq": 0, // type=print时：0=请求新任务，大于0=请求seq+1及后续资源
    "firmware": [ // type=print 时建议上报，用于云端判断是否需要推送固件升级
      {
        "firmwareType": "cloud", // 固件类型
        "firmwareVersion": "1.2.3", // 固件版本号
        "nn": "NN-001" // 模组NN号
      },
      {
        "firmwareType": "printer", // 固件类型
        "firmwareVersion": "3.4.5", // 固件版本号
        "nn": "NN-002" // 打印机NN号
      }
    ]
  },
  "ts": 1724044088000 // 消息时间戳（13位毫秒）
}

/up/pull 兼容旧结构：

{
  "msgId": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6", // 消息唯一ID，32字符
  "jobId": "", // 空=请求新任务，非空=请求该任务后续资源
  "seq": 0, // 0=请求新任务，大于0=请求seq+1及后续资源
  "firmware": [ // 兼容旧结构：固件列表
    {
      "firmwareType": "cloud", // 固件类型
      "firmwareVersion": "1.2.3", // 固件版本号
      "nn": "NN-001" // 模组NN号
    }
  ],
  "ts": 1724044088000 // 消息时间戳（13位毫秒）
}

7) `/down/print`

{
  "msgId": "e5f6789012a3b4c5d6e7f89012a3b4c5", // 消息唯一ID
  "jobId": "j-202408-0001", // 打印任务唯一ID
  "totalFileNumber": 100, // 任务文件总数
  "resources": [ // 打印资源列表
    {
      "seq": 1, // 资源序号，从1开始
      "url": "https://obj.example.com/prints/j-202408-0001-part1.data", // 文件下载URL
      "hash": "sha256:ab12cd34ef56...", // SHA256哈希值
      "size": 102400, // 文件大小（字节）
      "fileType": "prn", // 文件类型：prn/image
      "prnProtocol": "esc", // PRN协议类型：当前仅esc（fileType=prn时返回）
      "compression": "gzip" // 压缩方式：none/gzip
    },
    {
      "seq": 2, // 资源序号，从1开始
      "url": "https://obj.example.com/prints/j-202408-0001-part2.data", // 文件下载URL
      "hash": "sha256:cd34ef56ab78...", // SHA256哈希值
      "size": 102400, // 文件大小（字节）
      "fileType": "prn", // 文件类型：prn/image
      "prnProtocol": "esc", // PRN协议类型：当前仅esc（fileType=prn时返回）
      "compression": "none" // 压缩方式：none/gzip
    }
  ],
  "dateTime": 1724846400000 // 服务器时间（13位毫秒时间戳）
}

8) `/down/upgrade`

{
  "msgId": "f6789012a3b4c5d6e7f89012a3b4c5d6", // 消息唯一ID，32字符
  "deviceUpgradeId": "u-202408-0001", // 设备升级任务ID
  "firmwareType": "cloud", // 固件类型：cloud/printer/bluetooth
  "firmwareVersion": "1.2.4", // 固件版本号
  "url": "https://obj.example.com/fw/p5802-1.2.4.bin", // 固件下载URL
  "hash": "sha256:cd34ef56ab78...", // SHA256哈希值
  "size": 5242880, // 文件大小（字节）
  "compression": "gzip", // 压缩方式：none/gzip
  "dateTime": 1724846400000 // 服务器时间（13位毫秒时间戳）
}

9) `/down/control`

{
  "msgId": "h6i7j890k1l2m3n4o5p6q789r0s1t2u3", // 消息唯一ID
  "controlId": "a351eff1b614d0c1f64227d0c4b28c99", // 控制指令唯一ID
  "command": "reboot", // 控制指令类型
  "params": {}, // 可选：指令参数（预留字段）
  "dateTime": 1724846400000 // 服务器时间（13位毫秒时间戳）
}

10) `/down/pull/ack`

{
  "msgId": "m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8", // 消息唯一ID，32字符
  "ackOriginalMsgId": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6", // 原始 Pull 请求的 msgId
  "code": 0, // 响应码：0表示成功（但无可用任务）
  "message": "no_task", // 响应消息：no_task 表示无可用任务
  "dateTime": 1724044188000 // 服务器时间（13位毫秒时间戳）
}

11) `/down/resource`

{
  "msgId": "r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g6", // 消息唯一ID，32字符
  "ackOriginalMsgId": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6", // 对应 Pull 请求的 msgId
  "type": "feature_list", // 资源响应类型
  "errCode": [], // 错误码数组，[] 表示成功
  "msg": "", // 错误消息内容
  "params": { // 资源响应参数
    "features": [ // 功能列表
      {
        "featureCode": "print_basic", // 功能 code
        "featureName": "普通打印", // 功能名称
        "featureType": "normal" // 功能类型：normal/ai
      },
      {
        "featureCode": "ai_text_to_image", // 功能 code
        "featureName": "文生图打印", // 功能名称
        "featureType": "ai", // 功能类型：normal/ai
        "bizCode": "ai_doodle_swarmui_marker", // AI 业务 code
        "bizName": "文生图" // AI 业务名称
      }
    ]
  },
  "dateTime": 1724044288000 // 服务器时间（13位毫秒时间戳）
}

/down/resource 失败示例：

{
  "msgId": "r1s2t3u4v5w6x7y8z9a0b1c2d3e4f5g7", // 消息唯一ID，32字符
  "ackOriginalMsgId": "k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z7", // 对应 Pull 请求的 msgId
  "type": "text_to_image", // 资源响应类型（对应请求类型）
  "errCode": [2002], // 错误码数组，非空表示失败
  "msg": "text_to_image缺少prompt", // 错误消息内容
  "params": {}, // 失败场景通常为空对象
  "dateTime": 1724044289000 // 服务器时间（13位毫秒时间戳）
}

7. AI 可替换模块接入说明

7.1 文生图

通过 imageEngineCode + runtimeParams 对接。
对接实现需按租户提供的“文生图标准协议”开发（请求/响应字段、鉴权、超时、错误码）。

7.2 LLM

用于用户输入清洗、扩写、翻译、审核等。
建议实现 OpenAPI Chat Completions 兼容接口（默认路径可兼容 /v1/chat/completions）。

7.3 ASR

设备按 ASR 协议直接与云打印平台侧 ASR 服务交互。
云打印平台支持将该 ASR 服务接入租户提供的 ASR 平台。

8. 实施建议

先确认接入模式（设备级优先 or 租户级优先）。
先打通最小闭环：鉴权 -> 创建打印任务 -> 收到打印回执。
再接入消息汇聚（MQTT 或 HTTP 回调）。
最后接入 AI 可替换能力与高级流程。

租户开发接入文档

1. 文档说明

2. 租户视角平台架构

3. 两种接入模式与优势

4. 设备级接入流程

4.1 设备级核心 HTTP 接口

4.2 设备级 MQTT

5. 租户级接入流程

5.1 租户级核心 HTTP 接口

6. 租户 HTTP 回调包装协议

6.1 统一外层包装

6.2 全主题映射

6.3 上下线事件

设备上线

设备下线

6.4 各主题 data 内容示例

1) /up/state

2) /up/print/ack

3) /up/upgrade/ack

4) /up/control/ack

5) /up/event

6) /up/pull

7) /down/print

8) /down/upgrade

9) /down/control

10) /down/pull/ack

11) /down/resource

7. AI 可替换模块接入说明

7.1 文生图

7.2 LLM

7.3 ASR

8. 实施建议

1) `/up/state`

2) `/up/print/ack`

3) `/up/upgrade/ack`

4) `/up/control/ack`

5) `/up/event`

6) `/up/pull`

7) `/down/print`

8) `/down/upgrade`

9) `/down/control`

10) `/down/pull/ack`

11) `/down/resource`