docs(api): Phase 7e Template Layout System v2 — semantic schema + aggregation#86
Conversation
…ggregation Replaces the absolute-pixel-coordinate v1 schema with semantic layout fields. 3 canonical layouts: qr-left-text-right (1-N text lines next to QR), qr-only (full-height QR), and qr-with-listing (aggregation, 1 big label with N child items). Renderer auto-derives paddings + font sizes per tape_mm. All 12 existing seed templates rewritten + 3 new Kallax-Regal- Overview aggregation templates added. Hard cut from v1. Refs #22 Closes #81
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a significant redesign of the template layout system, moving from manual pixel-coordinate authoring to a semantic, renderer-driven model. By standardizing layout logic and automating geometry calculations, the system ensures consistent visual output across different tape widths while simplifying template creation. The update includes a new aggregation-capable layout and a strict migration path for existing seed templates. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a semantic layout system (v2) for label templates, transitioning from absolute pixel coordinates to intent-based declarations. The design includes Pydantic schema validation, deterministic geometry computation based on tape width, and a hard cut from the previous rendering engine. Review feedback identifies a regression in 62mm tape support for QL printers and documentation errors regarding DPI. Further improvements were suggested for layout validation, QR code scanability on small labels, and coordinate calculations to ensure compatibility with PIL's text rendering.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #86 +/- ##
==========================================
- Coverage 91.98% 91.09% -0.89%
==========================================
Files 70 71 +1
Lines 3055 3189 +134
Branches 261 271 +10
==========================================
+ Hits 2810 2905 +95
- Misses 181 216 +35
- Partials 64 68 +4
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR adds the Phase 7e design spec for moving templates from absolute-coordinate v1 definitions to a semantic v2 layout system with canonical QR/text layouts and aggregation support.
Changes:
- Defines Template Schema v2 with semantic layouts and renderer-computed geometry.
- Documents migration from seed v1 templates to v2, including aggregation templates.
- Lays out expected renderer, endpoint, testing, documentation, and Definition of Done work.
Comments suppressed due to low confidence (4)
docs/superpowers/specs/2026-05-17-phase-7e-template-layout-v2-design.md:76
- The
preview_sampletype does not support the aggregation sample shown later in this spec:itemsis a YAML list of objects, but this annotation only allows scalar values ortuple[str, ...]. Update the schema to allow nestedLabelDataItem/JSON values for aggregation previews, or the seededqr-with-listingtemplates will fail validation when their preview samples are parsed.
preview_sample: dict[str, str | int | float | bool | tuple[str, ...]] | None = None
docs/superpowers/specs/2026-05-17-phase-7e-template-layout-v2-design.md:217
- This snippet drops existing fields/config from
LabelData: the current model includes requiredsource_appand usesConfigDict(frozen=True)inbackend/app/schemas/label_data.py:21-27. Please show the extension as additive so the spec does not prescribe a breaking change or weaken the established immutability convention.
class LabelData(BaseModel):
model_config = ConfigDict(extra="forbid")
primary_id: str
title: str
qr_payload: str
secondary: tuple[str, ...] = ()
items: tuple[LabelDataItem, ...] = () # NEW — for qr-with-listing aggregation
docs/superpowers/specs/2026-05-17-phase-7e-template-layout-v2-design.md:201
make seed-resyncis described as an existing target, but there is no Makefile target with that name in the repository. Either add the target as part of the planned implementation or replace this with the actual supported operator command so the migration guidance is executable.
If a deployed DB has v1 templates seeded, they survive the upgrade until next seed-sync (then they get overwritten). To force-clean: operator runs `make seed-resync` (existing target) to wipe + re-seed from the new YAML files.
docs/superpowers/specs/2026-05-17-phase-7e-template-layout-v2-design.md:335
- These Definition of Done commands refer to make targets that do not currently exist (
make oapiandmake docs-svg-samples). The existing frontend Makefile exposesrefresh-snapshotandgen-clientinstead, so please either define these targets in the implementation plan or update the DoD to the actual commands contributors can run.
- [ ] `make oapi` regenerates client if any endpoint signature changed (likely none)
- [ ] `make docs-svg-samples` produces updated SVGs for all 15 (12 + 3 new) templates
- Fix DPI comment: 180 DPI → 300 DPI (pixel values match 300 DPI, not 180) - Fix PIL anchor: remove `+ first_line.font_size` from text line Y (PIL draw.text uses top-left anchor, not baseline; the offset would shift text block down) - Tighten qr-with-listing validation: "at least 1" → "exactly 1" text_line (renderer only uses text_lines[0] as item-line template; >1 silently ignored) - Fix listing_field/LabelData inconsistency: replace `compartments` examples with `items` everywhere (LabelData.items is the actual field; compartments was a stale placeholder that would fail runtime validation) Deferred (subjective / out-of-scope per §10): 62mm QL tape width, min-QR-size guard, model validator for tape-width limits Refs #22
## <small>0.6.1 (2026-05-19)</small> * fix(ui): preview-PNG data-URL must use template.URL type (#90) ([0f84976](0f84976)), closes [#90](#90) [#87](#87) [#22](#22) [#89](#89) [#22](#22) * docs(api): Phase 7c API-Auth design — 3-scope keys + rate-limit + /admin/api-keys UI (#85) ([8792e84](8792e84)), closes [#85](#85) [#22](#22) [#78](#78) [#85](#85) [#22](#22) [#79](#79) [#22](#22) * docs(api): Phase 7e Template Layout System v2 — semantic schema + aggregation (#86) ([0bab0c0](0bab0c0)), closes [#86](#86) [#22](#22) [#81](#81) [#22](#22) * chore(deps): bump the go-minor-and-patch group (#89) ([d6ba346](d6ba346)), closes [#89](#89) [skip ci]
Phase 7e spec. Decisions: hard cut, aggregation included as qr-with-listing layout, auto-derived constants, 3 canonical layouts. Implementation comes after Phase 7c. Refs #22 Closes #81
Spec polish — deferred suggestions
The following bot findings were reviewed and intentionally deferred:
max_text_linesin LAYOUT_CONSTANTS already documents the constraints. A cross-field Pydantic validator is a worthwhile hardening step; tracked as follow-up for Phase 7e implementation PR.