Run 2 Multi-Template — Implementation Summary

Date: 2026-04-09 → 2026-04-14 Repositories: operations, arda-frontend-app, documentation Plan: run-2-multi-template/project-plan.md Exit gate: plan/run-2-multi-template/validate-exit.sh Phase doc: phase-2-multi-template/verification.md

Status

All nine tracker tasks completed. Exit criteria passed.

The architectural core of the project. Replaced single-template enforcement with a group-by-template pipeline:

New CompositeRenderResult envelope with one GroupRenderResult per template group, each carrying its own templateId, description, url or error, and itemCount.
New PdfRenderService.renderGroups() primary entry point. The previous render() is now an internal helper.
Per-call batch splitting (maxItemsPerDocumintRequest = 40), bounded parallelism (maxParallelRenders = 3), and a per-request hard cap (maxItemsPerRequest = 200), all in module configuration.
Frontend rewritten to consume composite responses: opens one window per successful group and surfaces per-group errors as toasts; falls through to legacy single-URL handling for unchanged endpoints.
Card print-status update logic adapted: only cards in successful groups are marked PRINTED; cards in failed groups are left untouched.

Composite envelope at the service boundary, not as a wrapper added in the endpoint layer. Putting it in PdfRenderService made it easier for both ItemPrintingService and PrintLifecycleImpl to converge on the same data flow. See implementation-log § Run 2.
Synthetic RenderResult for cardPrinted() — the legacy cardPrinted() signature requires a single RenderResult. Run 2 constructed one synthetic value (job + asOf from the composite header, url + templateId from the first successful group) rather than overhauling that signature. The synthetic value is only used for print-event tracking, where the exact URL per card is never queried later. See implementation-log § T-2.5.
Bounded Semaphore-style concurrency rather than launching all groups unconstrained. Three is the deploy-time default; no per-tenant override.
Pre-flight maxItemsPerRequest rejection before any items are loaded or grouped, so the failure mode for an over-large request is fast and cheap.

make build in operations — green; new unit tests for grouping, batch splitting, and concurrency.
Frontend Jest + Playwright — green after a follow-up flake fix in #744.
Integration tests run locally against the ContainerizedPostgres harness; multi-template scenarios produced the expected number of result entries.

operations — #163 (merge 7a81c9c), the multi-template portion.
arda-frontend-app — #741 (merge b878516) for the composite-response handlers and #744 (merge eff365e) for the migration completion and flake fixes.