Specification: Phase 1 — Bug Fixes

This phase addresses three bugs in the current printing pipeline: incorrect card notes mapping (#815, #816), missing unmark-as-printed capability (#595), and verification of label/breadcrumb notes mapping.

Requirements: Phase 1 Requirements Verification: Phase 1 Verification Analysis: Gap Analysis — Gaps B-1, B-2, B-3

Task 1: Fix card notes mapping in KanbanCardPrinter

File: operations/src/main/kotlin/cards/arda/operations/resources/kanban/business/KanbanCardPrinter.kt Line: 48

Current code:

notes = if(card.notes == null || card.notes.isBlank())
  card.itemDetails.cardNotesDefault ?: card.itemDetails.notes ?: ""
else card.notes,

Change: Remove the fallback chain. When KanbanCard.notes is null or blank, use empty string:

notes = card.notes?.takeUnless { it.isBlank() } ?: "",

Tests: T-P1-001 through T-P1-004. Add or update tests in KanbanCardPrinterTest to verify:

• Card with notes = null → Documint notes = ""
• Card with notes = "" → Documint notes = ""
• Card with notes = "Custom note" → Documint notes = "Custom note"
• Card with notes = null, item with notes = "Ordered: 3/3/26..." → Documint notes = "" (not order history)

Requirement: REQ-P1-001

---

Task 2: Verify label/breadcrumb notes mapping in ItemPrinter

File: operations/src/main/kotlin/cards/arda/operations/reference/item/service/ItemPrinter.kt Lines: 106-107

Current code:

notes = item.notes ?: "",
card_notes = item.cardNotesDefault ?: "",

Action: Verify this is correct per specification. Item.notes maps to Documint notes — this is the expected behavior. Add tests if not already covered.

Tests: T-P1-005, T-P1-006. Verify in ItemPrinterTest:

• Label prints Item.notes in notes field
• Breadcrumb prints Item.notes in notes field

Requirement: REQ-P1-002

---

Task 3: Add UNMARK print event type (backend)

Files:

• operations/src/main/kotlin/cards/arda/operations/resources/kanban/business/KanbanCard.kt — Add UNMARK to KanbanCardPrintEventType enum
• operations/src/main/kotlin/cards/arda/operations/resources/kanban/service/PrintLifecycleImpl.kt — Add UNMARK → NOT_PRINTED mapping in _resultPrintState()

Changes:

1. In KanbanCardPrintEventType (KanbanCard.kt:62-70), add:

   UNMARK,

2. In _resultPrintState() (PrintLifecycleImpl.kt:62-72), add case:

   KanbanCardPrintEventType.UNMARK -> KanbanCardPrintStatus.NOT_PRINTED

3. Add unmarkPrinted() method to KanbanCardPrintLifecycle interface and implement in PrintLifecycleImpl:

   suspend fun unmarkPrinted(cardEId: UUID, effectiveTime: Timestamp, author: String): Result<KanbanCardPrintStateChange>

   Implementation delegates to _processPrintEvent(KanbanCardPrintEventType.UNMARK, ...).

Tests: T-P1-007 through T-P1-009.

Requirement: REQ-P1-003

---

Task 4: Expose unmark endpoint (API)

File: operations/src/main/kotlin/cards/arda/operations/resources/kanban/api/rest/KanbanCardEndpoint.kt

Change: Add a new POST endpoint following the existing print lifecycle pattern:

• Path: /kanban-card/{eId}/event/unmark
• Method: POST
• Request: No body (card identified by path parameter)
• Response: EntityRecord<KanbanCard, KanbanCardMetadata>
• Parameters: author (header), tenantId (header), effectiveAsOf (optional query)

Tests: T-P1-010, T-P1-011. Integration test with Harness.

Requirement: REQ-P1-004

---

Task 5: Frontend unmark action

Files:

• arda-frontend-app/src/app/api/arda/kanban/kanban-card/[eId]/unmark-printed/route.ts — New API route
• arda-frontend-app/src/components/items/CardInfo.tsx — Add unmark action to card dropdown menu

Changes:

1. Create Next.js API route proxying to POST /v1/kanban/kanban-card/{eId}/unmark-printed
2. In CardInfo.tsx, add a dropdown menu item “Unmark as printed” visible when printStatus === 'PRINTED'
3. On click, call the API route and refresh the card data
4. After success, card status should show NOT_PRINTED and button should read “Print card”

Tests: T-P1-012, T-P1-013. E2E test with Playwright.

Requirement: REQ-P1-005

---

Task 6: Update design documentation

Update the following documents to reflect Phase 1 changes:

1. Item Module (current-system/functional/reference-data/item/) — Verify the Payload Mapping section accurately reflects the notes mapping after Task 2 verification.
2. Kanban Cards Module (current-system/functional/resources/kanban-cards-module.md) — Add UNMARK event type to the print status documentation. Update the state machine diagram if present.

Tests: T-P1-018, T-P1-019. Review verification.

Requirement: REQ-P1-007

---

Task 7: Regression tests

Run the full existing test suite to verify no regressions:

• operations: make build (runs all tests with coverage)
• arda-frontend-app: npx jest --no-coverage --watchAll=false --forceExit + NEXT_PUBLIC_MOCK_MODE=true npm run test:e2e

Tests: T-P1-014 through T-P1-017.

Requirement: REQ-P1-006

---

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	What happens when UNMARK is called on a card not in PRINTED status?	A) Error (400) B) No-op (return current state)	A — explicit error prevents confusion	Option B: NoOp, No effect in other states, idempotent in NOT_PRINTED
2	Should the unmark endpoint path be /unmark-printed or reuse the existing print event pattern (e.g., /event/unmark)?	A) /unmark-printed (self-describing) B) /event/unmark (consistent with lifecycle events)	B — consistent with event/request, event/accept pattern	Agreed, Option B.
3	Should the frontend unmark action be in the card dropdown menu or a separate button?	A) Dropdown item B) Separate button	A — infrequent action, dropdown is appropriate	Agreed, Option A

---

STOP: Review Gate

Before proceeding to implementation, confirm:

• All open questions resolved
• Requirements approved
• Specification reviewed

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved