certflow.services.printer.print_queue module

打印队列服务（持久化队列管理）

提供基于数据库（print_jobs 表）的打印任务队列管理能力，与 UI/线程解耦。 负责任务的入队、出队、状态机流转、优先级重排与断电恢复。

设计要点： - 所有状态变更均落库（commit），保证断电可恢复； - 出队顺序由 (priority DESC, created_at ASC) 决定，支持置顶/上移； - 本服务为纯逻辑层，不直接调用打印机，打印动作由 QueueWorker 驱动。

class certflow.services.printer.print_queue.PrintQueueService(session)

基类：object

打印队列服务

围绕 print_jobs 表的队列管理。每个实例绑定一个 SQLAlchemy Session， 调用方需保证该 Session 在正确的线程中使用（跨线程请各自创建实例）。

示例

>>> svc = PrintQueueService(session)
>>> job = svc.enqueue(certificate_id=1, priority=5)
>>> next_job = svc.get_next_pending()
>>> svc.mark_running(next_job.id)
>>> svc.mark_done(next_job.id)

参数:

session (Session)

cancel_pending_by_certificate(certificate_id)

取消指定合格证的所有 pending 任务（用于 replace_pending 去重）。

仅取消 **pending**（尚未开始）的任务；running/paused/终态任务不动—— 正在打印的任务中途取消有风险，且终态任务无需处理。

参数:

certificate_id (int) -- 合格证批次 ID

返回:

被取消的 pending 任务数量

返回类型:

int

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

入队一个打印任务

参数:

• certificate_id (int | None) -- 关联合格证批次 ID（可为 None 表示纯展示任务）

• sn (str | None) -- 出厂编号（可选，用于单台任务或展示代表号）

• priority (int) -- 优先级，数值越大越优先出队

• replace_pending (bool) -- 为 True 时，入队前先取消该证已有的 pending 任务， 避免"重复点击入队"或"订正后再入队"产生同一证的多份 pending 导致重复打印。仅在 certificate_id 非空时生效。

返回:

新创建的任务对象（已落库，含自增 id）

返回类型:

PrintJob

bulk_enqueue(items, priority=0, *, replace_pending=False)

批量入队（保持传入顺序）

参数:

• items (Sequence[tuple[int | None, str | None]]) -- [(certificate_id, sn), ...] 列表

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

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

返回:

创建的任务列表

返回类型:

list[PrintJob]

get_next_pending()

取出下一个待打印任务（不出队，仅查询）

出队顺序：priority 降序、created_at 升序。

返回:

下一个 pending 任务；无则返回 None

返回类型:

PrintJob | None

count_pending()

统计 pending 任务数量

返回:

pending 任务数

返回类型:

int

get_job(job_id)

按 ID 获取任务

参数:

job_id (int) -- 任务 ID

返回:

任务对象或 None

返回类型:

PrintJob | None

mark_running(job_id, os_job_id=None)

标记任务为运行中（写入 started_at）

参数:

• job_id (int) -- 任务 ID

• os_job_id (int | None) -- 本次打印提交的 OS spooler 作业 ID（偏差 5 作业 ID 捕获链路），非 None 时一并持久化，供 OS 级取消使用。

返回类型:

PrintJob | None

set_os_job_id(job_id, os_job_id)

补写任务的 OS spooler 作业 ID（打印动作完成后回填）

与 mark_running() 解耦：部分场景下 OS 作业 ID 在 mark_running 之后、打印动作执行时才产生（见 BLUEPRINT §2.3 偏差 5）。

参数:

• job_id (int) -- 任务 ID

• os_job_id (int | None) -- OS 打印作业 ID；为 None 时忽略（不覆盖已有值）。

返回:

更新后的任务；任务不存在返回 None

返回类型:

PrintJob | None

mark_paused(job_id)

标记任务为已暂停（释放打印机，等待继续）

参数:

job_id (int)

返回类型:

PrintJob | None

mark_done(job_id)

标记任务为完成

参数:

job_id (int)

返回类型:

PrintJob | None

mark_error(job_id, error)

标记任务为失败并记录错误

参数:

• job_id (int)

• error (str)

返回类型:

PrintJob | None

mark_cancelled(job_id, error='用户取消')

标记任务为已取消

参数:

• job_id (int)

• error (str)

返回类型:

PrintJob | None

reorder_top(job_id)

将指定任务置顶（最高优先级出队）

参数:

job_id (int)

返回类型:

None

reorder_up(job_id)

将指定任务上移一位（与上一个 pending 任务交换顺序）

参数:

job_id (int)

返回类型:

None

list_jobs(include_terminal=True)

列出队列任务

参数:

include_terminal (bool) -- 是否包含已完成/取消的终态任务

返回:

任务列表（按 id 升序）

返回类型:

list[PrintJob]

clear_finished()

清理已完成的终态任务（done/cancelled）

返回:

删除的任务数量

返回类型:

int

recover()

断电/崩溃恢复：将 running/paused 任务重置回 pending

应用启动时调用，避免上次未完成任务卡在 running/paused 状态。

返回:

被恢复（重置为 pending）的任务数量

返回类型:

int