NTK-10005 — Add Wristband RFID Field to Check-In Record¶

Affected Capabilities¶

Affected Services¶

• svc-check-in

Solution Contents¶

• Requirements
• Analysis
• Decisions
• Impact Assessments (0)
• Implementation Guidance
• Capability Mapping

Related Solutions¶

Solutions that share services or capabilities with this design:

Problem Statement¶

NovaTrek Adventures is rolling out RFID-enabled wristbands for the 2026 summer season. Each wristband has two identifiers: a printed alphanumeric code (wristband_id, already supported) and an RFID chip identifier (rfid_tag, not yet captured at the check-in record level). Without the rfid_tag on the check-in record, kiosks cannot record scanned RFID data during check-in, and staff cannot look up a guest's check-in by scanning their wristband.

The WristbandAssignment sub-schema in svc-check-in already has an rfid_tag field, but the top-level CheckIn schema and the CheckInRecord Java entity do not. The GET /check-ins endpoint also lacks RFID-based filtering.

Architecture Classification¶

Classification: Code-Level Task (with light architecture review)

This is NOT a full architecture engagement. The reasoning:

1. Single service impact -- Only svc-check-in is modified. No new cross-service orchestration, communication patterns, or infrastructure components are introduced.
2. No new API endpoints -- The change adds a field to existing schemas and a query parameter to an existing endpoint.
3. No competing architectural approaches -- The change is straightforward: add a field, add validation, add a uniqueness constraint.
4. Existing patterns apply -- The WristbandAssignment schema already captures rfid_tag. This ticket extends that capture to the top-level CheckIn record for direct lookup.

Architecture review is recommended at the Swagger spec change stage (before merge) to confirm: - Uniqueness constraint scope (active check-ins only vs global) - Downstream event schema compatibility - RFID format alignment with hardware team specifications

Solution Overview¶

Add an optional rfid_tag field to the CheckIn schema in svc-check-in, the CheckInRecord JPA entity, and the check-in event payload. Add an rfid_tag query parameter to GET /check-ins for RFID-based lookup.

Changes Summary¶

Impacted Components¶

Changes Required¶

1. Swagger Specification Update¶

Add to the CheckIn schema:

rfid_tag:
  type: string
  maxLength: 64
  pattern: '^[A-F0-9]{8,16}$'
  nullable: true
  description: RFID chip identifier from the guest wristband
  example: "A3F7B20145CC"

Add to GET /check-ins parameters:

- name: rfid_tag
  in: query
  required: false
  schema:
    type: string
    pattern: '^[A-F0-9]{8,16}$'
  description: Filter check-ins by RFID wristband tag

2. JPA Entity Update¶

Add to CheckInRecord.java:

@Column(length = 64)
private String rfidTag;

3. Database Migration¶

ALTER TABLE check_in_records ADD COLUMN rfid_tag VARCHAR(64);

CREATE UNIQUE INDEX idx_rfid_tag_active 
ON check_in_records (rfid_tag) 
WHERE status NOT IN ('COMPLETED', 'FAILED');

4. Event Payload Update¶

Include rfid_tag as a top-level field in the check-in event. Downstream consumers using tolerant reader patterns will ignore the new field until they are ready to use it.

Validation Rules¶

• Format: Hexadecimal string matching regex ^[A-F0-9]{8,16}$
• Max length: 64 characters
• Nullable: Yes
• Uniqueness: Unique across active check-ins (status not in COMPLETED, FAILED)

Deployment Notes¶

• Database migration must run before the application deployment
• The schema change is additive and backward-compatible -- no consumer changes required
• Coordinate deployment with kiosk firmware update timeline (May 2026)
• Notify downstream event consumers of the new field in advance, even though no action is required from them

Related Artifacts¶

• Ticket Report
• Simple Explanation
• Assumptions
• Current State Investigation
• Decisions
• Guidance
• Impacts
• User Stories