[Bug]effective_at Time Restriction Issue When Using PATCH Update a card API

[Unmeiwa]

Description

When using the PATCH /v1/cards/{card_id} API to update a card, it was discovered that the new effective_at time is subject to an undocumented restriction. Specifically, the new effective_at time cannot be later than the currently set invalid_at time for the card.

Steps to Reproduce

Steps to reproduce the behavior:
1.Create or Edit a Card:
Use the POST /v1/cards or PATCH /v1/cards/{card_id} API to create or edit a card, setting the initial effective_at and invalid_at times. For example:
{
"display_name": "qwe",
"devices": ["uacxc"],
"effective_at": "2026-08-25T15:00:00Z",
"invalid_at": "2027-08-25T16:00:00Z",
"barcode_type": "qrcode",
"barcode_format": "png"
}
2.Attempt to Update the effective_at Time:
Use the PATCH /v1/cards/{card_id} API to update the card's effective_at time to be later than the current invalid_at time. For example:
{
"effective_at": "2030-08-25T15:00:00Z",
"invalid_at": "2031-08-25T16:00:00Z"
}
3.Submit the Update Request:
Send the update request and observe the response.

Actual Behavior

The update request is rejected with a message indicating that the effective_at time cannot be later than the invalid_at time.

Expected Behavior

It is expected to be able to set the effective_at time freely, even if it is later than the current invalid_at time.

Environment (if applicable)

• OS:Windows11
• Browser / Tool:Postman
• SDK / Client:
• Other relevant details:

Additional Context

If this is a protective rule of the system, it is recommended to clearly state it in the documentation.

[Iktahana]

Issue Verification: CONFIRMED ✓

The restriction is real and enforced by the system. Looking at the codebase:

Location: /internal/stayforge/card/domain/entity.go (lines 167-178) and /internal/stayforge/card/domain/value_objects.go (lines 154-162)

Current behavior:

• When updating effective_at via PATCH, the UpdateEffectiveAt() method calls ValidateDateRange(effectiveAt, c.InvalidAt)
• ValidateDateRange() enforces: if invalidAt.Before(*effectiveAt) || invalidAt.Equal(*effectiveAt) → returns error "invalid_at must be after effective_at"
• This means: You cannot set effective_at to a time that is >= the current invalid_at

Example from issue:

• Current card: effective_at: 2026-08-25T15:00:00Z, invalid_at: 2027-08-25T16:00:00Z
• PATCH request with: effective_at: 2030-08-25T15:00:00Z, invalid_at: 2031-08-25T16:00:00Z
• Result: ❌ Rejected because new effective_at (2030) is checked against current invalid_at (2027), and 2030 > 2027

Root cause: The validation logic doesnt account for the case where both effective_at and invalid_at are being updated together. It validates the new effective_at against the old invalid_at instead of against the new one.

Recommendation: When both fields are updated, validate the relationship between the new effective_at and new invalid_at values, not against the old values. Or document this as intended behavior and clearly state the constraint in API documentation.

[Washio20]

Automated Triage — Complex Bug

This issue has been triaged as complex and requires a design decision. The effective_at / invalid_at validation logic may be working as intended (preventing effective_at > invalid_at), but the PATCH endpoint should validate the new pair together rather than comparing the new effective_at against the old invalid_at.

@Iktahana — as the top contributor, could you please review the card update validation logic and clarify the intended business rules?

This comment was generated by an automated triage system.

[Washio20]

Not a Bug — Triage Notice

After automated analysis, this issue does not appear to be a bug. Reason: The API correctly validates that effective_at cannot be later than invalid_at — a card should not become effective after its expiry. However, when both fields are updated simultaneously in the same PATCH request (as shown in the example where new effective_at < new invalid_at), the API may be validating against the old invalid_at instead of the new one — if so, that would be a legitimate bug in validation ordering.

@Iktahana — as the top contributor to this repository, could you please review this issue and consider:

• Verifying whether PATCH validates against old vs new invalid_at
• If validation is correct, removing the bug label and relabelling as enhancement or documentation
• Adding documentation for this validation rule

This comment was generated by an automated triage system.

[Washio20]

Automated Triage — Complex Bug

This issue has been triaged as complex and requires human review.

Reason: The effective_at validation against the existing invalid_at when both fields are being updated simultaneously may be an intentional business rule or a validation ordering issue. This requires a design decision: should the API validate the new effective_at against the new invalid_at (from the same request) rather than the old one?

@Iktahana — as the top contributor, could you please clarify the intended validation behavior and document it?

This comment was generated by an automated triage system.

[Washio20]

Automated Triage — Complex Bug

This issue has been triaged as complex and requires a design decision.

Reason: The effective_at vs invalid_at validation during PATCH updates appears to validate the new effective_at against the existing invalid_at before applying the full update. This requires a design decision: should the validation compare the new effective_at against the new invalid_at (when both are provided in the same PATCH), or should the current restriction be documented as intended behavior?

@Iktahana — as the top contributor to this repository, could you please review this issue and determine the intended validation behavior?

This comment was generated by an automated triage system.

[Washio20]

Automated Triage — Complex Bug

This issue has been triaged as complex and requires a design decision.

Reason: The effective_at time restriction when updating cards (PATCH) may be an intentional validation rule rather than a bug. The system currently prevents setting effective_at later than invalid_at, which is logically sound as a card shouldn't be effective after it expires. However, when both fields are updated simultaneously (as in the reproduction steps), the validation should compare the new effective_at against the new invalid_at, not the current one.

This requires a design decision:

1. Is the cross-field validation intentional?
2. Should simultaneous updates be evaluated atomically (new effective_at vs new invalid_at)?

@Iktahana — as the top contributor to this repository, could you please clarify the intended behavior?

This comment was generated by an automated triage system.

[Washio20]

Triage: Complex — Requires Human Review

After automated analysis, this issue has been classified as complex and requires human investigation.

Reason: The effective_at time restriction when updating cards may be an intentional business rule (preventing cards from having an effective date after their invalidation date). The fix requires a design decision:

• Should the API allow effective_at > invalid_at when both are being updated simultaneously?
• Should validation compare against the new invalid_at value rather than the current one?

This requires understanding the business logic intent, not just a code change.

Assigning to the top contributor for review.

@Iktahana — could you please investigate and clarify the intended behavior?

This comment was generated by an automated triage system.

[Washio20]

Automated Triage — Complex Bug

This issue has been triaged as complex and requires human review.

Reason: The effective_at validation against invalid_at may be intentional business logic. Changing this behavior requires a design decision about whether to allow overlapping/sequential validity periods when both fields are updated simultaneously in a PATCH request.

Assigning to repository owner for investigation.

This comment was generated by an automated triage system.