certflow.controllers.print_queue_controller module

打印队列控制器

协调打印队列的异步执行与 UI 交互。封装 QueueWorker 线程与信号机制， 通过 Qt 信号槽实现非阻塞的队列处理，支持入队、暂停、继续、取消、置顶、上移。

架构位置：View → PrintQueueController → PrintQueueService（DB）/ CertificatePrintService（打印） 队列持久化于 print_jobs 表，断电重启后可恢复。

信号约定（小写_下划线 + 语义后缀）：

queue_changed: 队列内容变化（增删/状态变更/重排）时发出 job_started: 某任务开始打印 (job_id) job_finished: 某任务结束 (job_id, success, message) status_changed: 控制器状态文本变化 (message) progress_updated: 当前任务进度 (current, total)

class certflow.controllers.print_queue_controller.QueueWorker(controller)

基类：QThread

队列执行工作线程

在独立线程中循环取出 pending 任务并打印，避免阻塞 UI 主线程。 每完成一个任务后检查暂停/取消标志，保证安全中断。

Signals:

job_started: 任务开始 (job_id) job_finished: 任务结束 (job_id, success, message) status_changed: 状态文本 (message) queue_changed: 队列内容变化

参数:

controller (PrintQueueController)

job_started

job_finished

status_changed

queue_changed

stop()

请求停止工作线程

返回类型:

None

run()

返回类型:

None

staticMetaObject = PySide6.QtCore.QMetaObject("QueueWorker" inherits "QThread": Methods:   #12 type=Signal, signature=job_started(int), parameters=int   #13 type=Signal, signature=job_finished(int,bool,QString), parameters=int, bool, QString   #14 type=Signal, signature=status_changed(QString), parameters=QString   #15 type=Signal, signature=queue_changed() )

class certflow.controllers.print_queue_controller.PrintQueueController(db_manager=None, session_factory=None, printer_name='', print_func=None)

基类：QObject

打印队列控制器

管理队列生命周期：入队、启动、暂停、继续、取消、重排、清理与恢复。 通过 Qt 信号槽与视图解耦。

参数:

• db_manager (DatabaseManager | None)

• session_factory (Callable[[], Session] | None)

• printer_name (str)

• print_func (PrintFunc | None)

_session_factory

返回新 Session 的工厂（多线程各自创建，避免共享）

_printer_name

默认打印机名称

_print_func

打印动作（可注入，便于测试）

_worker

当前队列工作线程

_paused

暂停标志

_cancel_job_id

运行中待取消的任务 ID（None 表示无）

queue_changed

队列内容变化信号

job_started

任务开始信号 (job_id)

job_finished

任务结束信号 (job_id, success, message)

status_changed

状态文本信号 (message)

progress_updated

进度信号 (current, total)

enqueue(certificate_id, sn=None, priority=0, *, replace_pending=False)

入队一个打印任务

参数:

• certificate_id (int | None) -- 关联合格证批次 ID

• sn (str | None) -- 出厂编号（可选）

• priority (int) -- 优先级

• replace_pending (bool) -- 为 True 时入队前先取消该证已有 pending 任务，避免 重复点击/订正后再入队产生同证多份 pending 而重复打印。

返回:

新任务 ID

返回类型:

int

enqueue_certificates(certificate_ids, priority=0, *, replace_pending=False)

批量入队多个 Certificate

参数:

• certificate_ids (list[int]) -- Certificate.id 列表

• priority (int) -- 统一优先级

• replace_pending (bool) -- 为 True 时每个证入队前先取消其已有 pending 任务（去重）。

返回:

创建的任务 ID 列表

返回类型:

list[int]

start()

启动队列工作线程（若未运行）

返回类型:

None

stop()

停止队列工作线程（等待退出）

返回类型:

None

pause()

暂停队列（不再启动新任务；当前任务完成后停止）

注：中途 ESC/P-K 指令流的安全中断依赖真机验证（P0）， 当前版本采用任务边界暂停语义。interrupt_current() 预留 OS 级取消钩子。

返回类型:

None

resume()

继续队列

返回类型:

None

is_paused()

是否处于暂停状态

返回:

True 表示已暂停

返回类型:

bool

is_running()

工作线程是否在运行

返回:

True 表示运行中

返回类型:

bool

cancel_job(job_id)

取消任务

• pending：立即标记取消（不再打印）

• running：设置取消标记，当前任务结束后标记为取消，并尝试 OS 级中断

参数:

job_id (int) -- 任务 ID

返回类型:

None

move_top(job_id)

置顶任务

参数:

job_id (int)

返回类型:

None

move_up(job_id)

上移任务

参数:

job_id (int)

返回类型:

None

clear_finished()

清理已完成任务

返回:

删除的任务数

返回类型:

int

recover()

启动时恢复未完成任务

返回:

被重置为 pending 的任务数

返回类型:

int

list_jobs(include_terminal=True)

列出队列任务（字典形式，供视图渲染）

参数:

include_terminal (bool) -- 是否包含终态任务

返回:

任务字典列表

返回类型:

list[dict]

staticMetaObject = PySide6.QtCore.QMetaObject("PrintQueueController" inherits "QObject": Methods:   #4 type=Signal, signature=queue_changed()   #5 type=Signal, signature=job_started(int), parameters=int   #6 type=Signal, signature=job_finished(int,bool,QString), parameters=int, bool, QString   #7 type=Signal, signature=status_changed(QString), parameters=QString   #8 type=Signal, signature=progress_updated(int,int), parameters=int, int )

count_pending()

统计 pending 任务数

返回:

pending 数量

返回类型:

int

set_printer(printer_name)

设置默认打印机

参数:

printer_name (str) -- 打印机名称

返回类型:

None

classmethod status_label(status)

打印任务状态中文标签（替代视图对 PrintJobStatus 枚举的直连）。

参数:

status (str)

返回类型:

str

classmethod status_color(status)

打印任务状态配色（替代视图对 PrintJobStatus 枚举的直连）。

参数:

status (str)

返回类型:

str