Skip to main content

Developer-ready checklist for Module 5: Labels (GHS / NFPA / HMIS). It mirrors prior modules with acceptance criteria, edge cases, QA matrix, security, observability, and DoD so the team can build and verify step-by-step.

5. Labels Module — Developer Checklist

0) Foundations (blockers if incomplete)​

Feature flags: labels.ghs, labels.nfpa, labels.hmis, labels.batch_print, labels.custom_templates, labels.direct_print, labels.branding. Services/creds: PDF renderer (ReportLab/React-PDF), PNG exporter, printer bridge (Zebra Browser Print / CUPS), object storage for generated files, Sentinel webhook bus. DB migrations: labels, label_templates, label_print_history, label_audit_log, add current_sds_id to chemicals if not present. Access control: RLS by company_id and site_id; only roles with “Label:Generate” can print; read-only for others. Assets: GHS pictogram SVG set, NFPA 704 diamond renderer, HMIS bar/PPE icons.

5.1 Purpose (analytics & compliance hooks)​

Track key events: label_preview_opened, label_generated, label_printed, label_batch_printed, label_generation_failed. Persist link to SDS version used at generation time. Expose download path for inspectors (Admin → Audit Logs). Acceptance: Each label action recorded; label → chemical → SDS version traceable.

5.2 Scope & Entitlements​

Standard/Pro only: enforce feature availability by tier. Pro enables: template mixing, custom templates upload, direct printer integration, API-triggered batch, per-site branding. Acceptance: Tier change updates UI and API permissions immediately.

5.3 Label Generation Flow​

5.3.1 Select Chemical​

From inventory table: “Generate Label” action requires site/location context. Preload SDS metadata (Section 1 & 2 summaries). Warn if no SDS or SDS not parsed (block or allow with “missing data” banner per policy). Acceptance: Selected chemical loads preview with SDS-backed fields or clear blocking message.

5.3.2 Choose Label System​

Options: GHS, NFPA 704, HMIS; Pro: combo (e.g., GHS + NFPA). System switches layout engine and required fields accordingly. Acceptance: Switching systems updates preview & validations instantly.

5.3.3 Auto-Populate Fields​

Pull from SDS & system: Product Identifier (Sec 1), Manufacturer (Sec 1), Signal Word (Sec 2), Hazard statements (H-codes), Precautionary (P-codes), Pictograms, Optional: lot, site, print date, responsible person. Validation: mismatch between chosen pictograms and hazard statements flagged; cannot proceed if critical. Acceptance: Fields auto-fill correctly; validator catches mismatches before print.

5.3.4 Branding (Optional)​

Company logo upload or pick existing; per-site override (Pro). Footer: company/site name, contact. Acceptance: Branding renders crisply on all sizes; can be toggled per template.

5.4 Templates, Sizes & Layout​

5.4.1 Built-in Templates​

Predefined sizes: 1"x2", 2"x4", 4"x6"; orientations: horizontal/vertical. Text scaling & line-wrapping; dynamic pictogram layout; font fallback. Acceptance: Content fits without overflow at all sizes (auto scale).

5.4.2 Custom Templates (Pro)​

Upload SVG/JSON template with slots (e.g., {product_identifier}, {h_statements}, {pictograms}). Validate placeholders; preview before save; store at site or org scope. DPI/print density fields persisted per template. Acceptance: Uploaded templates render with sample data; invalid templates rejected with reasons.

5.5 Preview & Print​

5.5.1 Preview​

Live canvas preview; reorder text blocks (drag) & toggle sections (e.g., show/hide PPE line). Accessibility: zoom, high-contrast toggle. Acceptance: Preview reflects edits instantly; no visual clipping.

5.5.2 Export / Print Options​

PDF and PNG exports saved to storage with signed URLs (short TTL). Direct print (Pro): Zebra/Dymo bridge; support printer selection & status return. Batch print: multi-select chemicals → queued job → single PDF per template or per-label pages. Record to label_print_history on export/print. Acceptance: Files downloadable/printable; history row created with status and page count.

5.6 Data Sources (hard guarantees)​

Map fields to sources exactly as specified: Product Identifier → Inventory (SDS Sec 1 consistency check) Signal Word / H / P / Pictograms → SDS Sec 2 (parsed) Manufacturer Contact → SDS Sec 1 Date Printed → system timestamp If parser missing fields → allow manual override with explicit warning; log label_fields_overridden. Acceptance: All displayed data has provenance; overrides are auditable.

5.7 Audit & Recordkeeping​

5.7.1 Label Logs​

Write label_audit_log with: chemical_id, sds_id, label_type, template_id, user_id, site_id, timestamp, source (UI/API), result (success/fail), file_ref. Expose CSV export in Admin → Audit Logs with filters. Acceptance: Auditors can export and trace any printed label to SDS version.

5.7.2 PDF Archive (optional)​

Policy toggle to retain generated PDFs (size-capped, retention window). Link archive to audit detail. Acceptance: If enabled, PDFs available during retention; otherwise metadata only.

5.8 Notifications & Alerts (by tier)​

Label Generated: Standard(Email summary), Pro(Email + Webhook). Batch Printed: Standard(Email), Pro(Email + In-app toast). Missing Label Data: Standard(Email), Pro(Sentinel alert). Printer Error: Standard(Email), Pro(Webhook + error surface in UI). Audit Export: Pro(Webhook to Admin). Acceptance: Signals match tier and are deduped; recipients configurable per site.

5.9 Tier Enforcement​

Standard: built-in templates, PDF/PNG export, email alerts, logs. Pro: custom templates, direct print, API batch, per-site branding, webhook alerts, versioned SDS linkage in audit. Acceptance: Upgrading unlocks features instantly; downgrading hides and blocks API routes.

5.10 Implementation (done-state confirmations)​

Label microservice consumes chemicals + sds_documents (and sds_sections) via internal API. Rendering engine supports vector pictograms & high-DPI output. Printer connector health-check endpoint and UI status badge. Sentinel integration emits label.activity events. Public API POST /labels/generate (Pro) with idempotency key, rate limits, and tenant scope. Acceptance: Service handles concurrent jobs; idempotent; errors surfaced with actionable codes.

Security Checklist (must-pass)​

Tenant isolation: all read/write scoped by company_id and site_id (RLS). Data integrity: cannot print without selecting a chemical in current tenant; SDS version pinned at generation. File safety: exports stored with signed URLs (short TTL), private by default; no public buckets. Template safety: sanitize uploaded SVG/JSON; disallow scripts; validate placeholders. Printer security: local bridge uses mutual auth or secure channel; no raw unauthenticated print endpoints. Audit immutability: label_audit_log append-only (soft-delete admin-only for PII requests with reason). Rate limiting on generate endpoints; protect against automated spam.

QA Test Matrix​

Happy Paths GHS label from chemical with complete SDS → auto-filled fields render; PDF prints; audit row linked to SDS version. NFPA 704 diamond with correct ratings; visual matches spec; PNG export crisp. HMIS label with PPE icons; text wraps correctly on 1"x2". Pro: custom SVG template uploaded → placeholders validated → preview renders → direct print to Zebra works. Batch print 25 chemicals → single PDF produced; history shows 25 items; email summary sent. Edge Cases Missing SDS → generation blocked or allowed with override (per policy) and “Missing data” banner; audit notes override. Conflict: pictograms don’t match hazards → validation prevents print until corrected. Very long product name → auto-scale & wrap; no clipping at 1"x2". Printer offline → error surfaced; retry/log; Pro webhook fired. Template JSON missing required slot → upload rejected with detailed errors. User from different site attempts to print → RLS denies; user-friendly error. Cross-Platform PDF looks identical on macOS/Windows/Linux viewers; Zebra/Dymo sample prints aligned. RTL/locale text doesn’t break layout; EN/ES strings localized. Performance Preview render < 300ms p95. PDF generation < 2s p95 for single; batch 25 < 10s p95. Print job round-trip status < 3s p95 (local bridge).

Observability / Alerts​

Dashboards: labels by type/time/site, failure rate, average render time, printer status. Alerts: spike in label_generation_failed, printer offline > N min, webhook delivery failures, SDS-mismatch validation spikes.

Deliverables (Definition of Done)​

Figma: Label picker, system chooser, preview with edits, branding controls, template manager, batch selection, error/empty states. OpenAPI: /labels/generate, /labels/preview, /labels/templates, /labels/print, /labels/audit documented with examples. Localization: EN/ES for UI + emails. E2E tests (Cypress/Playwright) for happy paths + edge cases above. Admin tools: re-render with different template; re-link label to chemical/SDS; export audit logs. Rollback plan: disable direct print/custom templates via flags; core PDF/PNG path remains functional.

Want me to proceed with the Module 6: HazCom Plan Builder developer checklist next (AI analyzer, DOCX/PDF generation, versioning, approvals, and training auto-generation)?