Specification: Phase 3 — Print Diagnostics

This phase adds diagnostic query parameters (debug, dry-run) to all print endpoints, enabling the Customer Support persona to inspect Documint payloads and test print configurations without consuming production quota.

Requirements: Phase 3 Requirements Verification: Phase 3 Verification Analysis: Gap Analysis — Gaps D-1, D-2, D-3 Depends on: Phase 2 (multi-template printing) should be complete — diagnostics benefit from the refactored printing pipeline and composite response shape.

Task 1: Add debug and dry-run parameters to endpoints

Files:

operations/src/main/kotlin/cards/arda/operations/reference/item/api/rest/ItemEndpoint.kt — print-label, print-breadcrumb routes
operations/src/main/kotlin/cards/arda/operations/resources/kanban/api/rest/KanbanCardEndpoint.kt — print-card route

Change: Add debug and dry-run optional boolean query parameters to all three print endpoints. Pass them through to the service layer.

Requirement: REQ-P3-001, REQ-P3-002

Task 2: Extend PdfRenderService for diagnostic modes

Files:

operations/src/main/kotlin/cards/arda/operations/shopaccess/pdfrender/service/PdfRenderService.kt

Change: Extend the render() method (or add an overload) to accept debug and dryRun flags:

suspend fun render(
  job: RenderJob,
  author: String,
  live: Boolean?,
  debug: Boolean = false,
  dryRun: Boolean = false
): Result<RenderResult>  // or a diagnostic wrapper type

When dryRun=true:

Skip the DocumintProxy.render() call
Return a result containing the payload that would have been sent
The url in the result is null

When debug=true (and dryRun=false):

Execute the normal render
Include the payload in the response alongside the PDF URL

Define a diagnostic response wrapper:

@Serializable
data class DiagnosticRenderResult(
  val result: RenderResult?,      // null for dry-run
  val payload: JsonElement?,      // included when debug=true or dryRun=true
  val templateConfig: PrintingTemplateConfiguration?
)

Tests: T-P3-004 through T-P3-008.

Requirement: REQ-P3-001, REQ-P3-002, REQ-P3-003

Task 3: Wire diagnostic parameters through printing services

Files:

operations/src/main/kotlin/cards/arda/operations/reference/item/service/ItemPrintingService.kt
operations/src/main/kotlin/cards/arda/operations/resources/kanban/service/PrintLifecycleImpl.kt

Change: Pass debug and dryRun flags from the endpoint through to PdfRenderService.render(). When dryRun=true, skip print status updates for cards (no side effects).

Requirement: REQ-P3-002

Task 4: Integrate diagnostic output with composite response

Change: Extend CompositeRenderResult (from Phase 2) to optionally include diagnostic payload when debug=true or dryRun=true:

@Serializable
data class GroupRenderResult(
  val templateId: String,
  val description: String,
  val itemCount: Int,
  val url: URL? = null,
  val error: String? = null,
  val debugPayload: JsonElement? = null  // included when debug or dryRun
)

Tests: T-P3-001 through T-P3-003, T-P3-006.

Requirement: REQ-P3-001, REQ-P3-002

Task 5: Update design documentation

PDF Render Module (current-system/functional/shop-access/pdf-render-module.md) — Add debug and dryRun parameters to the PdfRenderService interface. Add a sequence diagram for the dry-run path. Document the diagnostic response types.
Item Module (current-system/functional/reference-data/item/) — Document debug and dry-run query parameters on the print endpoint table.

Tests: T-P3-012, T-P3-013.

Requirement: REQ-P3-005

Task 6: Regression tests

Run full test suites:

operations: make build
Verify existing print tests still pass with default parameter values (debug=false, dryRun=false)

Tests: T-P3-010, T-P3-011.

Requirement: REQ-P3-004

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Should diagnostic parameters be available to all authenticated users or restricted to a support role?	A) All authenticated users B) Support role only (checked via header or claim)	A for now — role-based access is a separate concern. The parameters are harmless (debug adds data, dry-run prevents side effects).	Agreed
2	Should the `debugPayload` field be excluded from non-debug responses entirely, or present as null?	A) Omit field (not in JSON) B) Include as null	A — cleaner response; `@JsonInclude(NON_NULL)` equivalent via `@EncodeDefault(NEVER)`	Agreed

STOP: Review Gate

Before proceeding to implementation, confirm:

All open questions resolved
Requirements approved
Specification reviewed
Phase 2 complete and verified