当前开启打印流程

本文档记录当前 C 客户端、C SDK 和 tijet_1/tincore gRPC 服务端的实际开启打印流程。

本文档只描述当前代码和当前客户端行为，不包含未来改造方案。

源码基准

模块	代码库	分支
Proto 契约与 C SDK	`tijet_1/sw-grpc-libraries`	`master`
tincore gRPC 服务端	`tijet_1/tincore`	`feature-grpc-cpp`

参与者

参与者	职责
Qt 客户端业务层	注册事件回调、上传打印数据、重试 `START_PRINT`、等待最终结果
C SDK 调用线程	封装 `SetPrintData` 和 `StartPrint` RPC
C SDK 事件线程	持续读取 `SubscribeEvents` 服务端流，并调用客户注册的事件回调
`TinCoreServiceImpl`	gRPC 协议层，将 RPC 请求转交给服务端 Handler
`DefaultTinCoreHandlers`	执行打印数据接收、数据就绪校验和异步开启打印逻辑
`gAFBridge` / 喷头硬件	后台处理打印数据、控制驱动板电源、与喷头通信并开启高压

当前调用时序

sequenceDiagram
    autonumber
    participant Caller as 调用端
    participant Callee as 被调用端

    Caller->>Callee: tijet_client_set_event_callback(callback, user_data)
    Callee-->>Caller: 回调注册完成

    Caller->>Callee: tijet_client_start_event_subscription()
    Callee-->>Caller: TIJET_OK
    Note over Callee: 后台创建事件线程
    Note over Callee: SubscribeEvents() 持续读取

    Caller->>Callee: tijet_client_set_print_data(data, index, is_static)
    Callee-->>Caller: SetPrintDataResponse{success=true}
    Note over Callee: 打印数据进入后台处理
    Note over Callee: 返回时 DATA_READY 可能仍为 0

    loop START_PRINT 重试，总超时 10 秒
        Caller->>Callee: tijet_client_print_control(START_PRINT)
        alt DATA_READY == 0
            Callee-->>Caller: TIJET_ERR_SERVER
            Note over Caller: 等待 1 秒后重试
        else DATA_READY != 0
            Callee-->>Caller: TIJET_OK
            Note over Callee: 创建高压启动线程
        end
    end

    Note over Caller: START_PRINT 成功后，等待 PrintStarted

    alt 高压开启成功
        Callee-->>Caller: PrintStarted{success=true}
        Note over Caller: 可进入喷印状态
    else 高压开启失败
        Callee-->>Caller: PrintStarted{success=false}
        Note over Caller: 失败，message 含未就绪喷头数
    else 10 秒未收到 PrintStarted
        Note over Caller: 等待超时
    end

重试与超时流程

flowchart TD
    A["调用端: 连接服务端"] --> B["调用端: 注册事件回调<br/>启动事件订阅"]
    B --> C["调用端: set_print_data() 上传打印数据"]
    C --> D{"被调用端: 上传 RPC 成功？"}

    D -->|"否"| D1["失败，流程结束"]
    D -->|"是"| E["被调用端: 数据进入后台处理<br/>DATA_READY 可能仍为 0"]

    E --> F["调用端: 开始 START_PRINT 重试计时"]
    F --> G["调用端: print_control(START_PRINT)"]
    G --> H{"被调用端: DATA_READY 是否为 0？"}

    H -->|"是：数据未就绪"| I{"重试总时间达 10 秒？"}
    I -->|"否"| J["调用端: 等待 1 秒"]
    J --> G
    I -->|"是"| K["失败：打印数据准备超时"]

    H -->|"否：数据已就绪"| L["被调用端: 创建高压启动线程<br/>返回 TIJET_OK"]
    L --> M["调用端: 等待 PrintStarted 事件<br/>超时 10 秒"]
    M --> N{"结果"}

    N -->|"success=true"| O["成功：高压开启完成<br/>进入可喷印状态"]
    N -->|"success=false"| P["失败：高压开启失败"]
    N -->|"超时"| Q["失败：等待高压结果超时"]

返回值的当前含义

位置	返回值	当前实际含义
`tijet_client_set_print_data()`	`TIJET_OK`	打印数据上传 RPC 已完成；不表示后台数据处理完成，也不表示 `DATA_READY=1`
`tijet_client_print_control(..., "START_PRINT")`	`TIJET_ERR_SERVER`	gRPC 调用失败，或服务端返回 `success=false`；当前客户端不区分原因，统一等待 1 秒后重试
`tijet_client_print_control(..., "START_PRINT")`	`TIJET_OK`	服务端同步校验通过并创建了高压启动线程；不表示高压已经开启
`PrintStarted.success`	`true`	高压开启成功，并已调用 `setDataParamReady(true)`
`PrintStarted.success`	`false`	高压开启失败，`message` 包含未就绪喷头数量

源码索引

C SDK

sdk/c/src/tijet_core.cpp:342：tijet_client_set_print_data()。
sdk/c/src/tijet_core.cpp:396：注册事件回调。
sdk/c/src/tijet_core.cpp:408：启动事件订阅和创建事件线程。
sdk/c/src/tijet_core.cpp:641：tijet_client_print_control()。
sdk/c/src/tijet_core.cpp:655：匹配 START_PRINT 并调用 StartPrint RPC。
sdk/c/include/tijet_core.h:441：打印数据上传 C API 声明。
sdk/c/include/tijet_core.h:480：事件回调注册 C API 声明。
sdk/c/include/tijet_core.h:500：事件订阅 C API 声明。
sdk/c/include/tijet_core.h:650：打印控制 C API 声明。

Proto 契约

proto/print.proto:7：SetPrintDataRequest。
proto/print.proto:19：StartPrintRequest。
proto/print.proto:22：StartPrintResponse。
proto/event.proto:48：PrintDataStatus。
proto/event.proto:53：PrintStarted。
proto/tincore.proto:27：SetPrintData RPC。
proto/tincore.proto:28：StartPrint RPC。
proto/tincore.proto:33：SubscribeEvents RPC。

`tijet_1/tincore` gRPC 服务端

以下路径相对于 tijet_1/tincore 代码库的 feature-grpc-cpp 分支：

src/grpc/tincore_service_impl.cpp:210：接收 SetPrintData 客户端流。
src/grpc/default_tin_core_handlers.cpp:211：将打印数据交给 gAFBridge->writePrintData()。
src/grpc/tincore_service_impl.cpp:130：处理 StartPrint RPC。
src/grpc/default_tin_core_handlers.cpp:370：同步检查 PARAM_INDEX_RO_DATA_READY。
src/grpc/default_tin_core_handlers.cpp:386：后台开启驱动板电源和高压。
src/grpc/tincore_service_impl.cpp:237：处理 SubscribeEvents 服务端流。
src/grpc/tincore_service_impl.cpp:285：将内部 printStarted JSON 映射为 EventReport.print_started。

当前已知问题

C SDK 头文件示例使用小写 "start_print"，实现只匹配大写 "START_PRINT"。客户照头文件示例调用时会得到 TIJET_ERR_INVALID_ARG。
tijet_client_set_print_data() 返回 TIJET_OK 时，打印数据可能仍在 gAFBridge 中后台处理，不能据此判断至少一份数据已经就绪。
Proto 已定义 PrintDataStatus，但当前服务端没有生成或映射该事件，客户端无法通过该事件等待数据就绪。
C SDK 没有检查 SetPrintDataResponse.success，只检查 gRPC Status。如果 RPC 状态为 OK、响应中的 success=false，C SDK 仍会返回 TIJET_OK。
当前客户端对所有 START_PRINT 失败执行相同的每秒重试，不区分缓冲数据不足、RPC 失败或其他服务端错误。
START_PRINT 返回 TIJET_OK 只表示服务端创建了后台线程；最终高压结果必须从独立的 PrintStarted 事件获得。
StartPrintResponse 与 PrintStarted 之间没有请求 ID 或其他关联字段。
PrintStarted 依赖事件订阅已经建立；没有有效订阅时，后台线程不会向该客户端交付最终结果。
tijet_client_start_event_subscription() 创建事件线程后立即返回，不等待服务端完成 SubscribeEvents 建立，因此“启动订阅返回成功”和“服务端可以推送事件”之间存在时间窗口。

当前开启打印流程

源码基准

参与者

当前调用时序

重试与超时流程

返回值的当前含义

源码索引

C SDK

Proto 契约

tijet_1/tincore gRPC 服务端

当前已知问题

`tijet_1/tincore` gRPC 服务端