feat(dispenser): recover K720 card position during uncertain encoding

This commit is contained in:
2026-10-22 18:56:22 +01:00
parent 28aea4aab2
commit 8c5e61efd0
6 changed files with 472 additions and 20 deletions
+112 -17
View File
@@ -545,10 +545,24 @@ func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string)
return r.status, stock, nil
}
func (c *Client) prepareCardAtEncoder(parent context.Context, operation string) (stock string, resultErr error) {
// PreparationResult carries this issuance attempt's handoff and recovery budget.
type PreparationResult struct {
Stock string
UncertainHandoff bool
ShakesUsed int
lastFC7 time.Time
}
func (c *Client) prepareCardAtEncoder(ctx context.Context, operation string) (string, error) {
preparation, err := c.prepareCardForEncoding(ctx, operation)
return preparation.Stock, err
}
func (c *Client) prepareCardForEncoding(parent context.Context, operation string) (preparation PreparationResult, resultErr error) {
status, stock, err := c.waitForDeliveryClearance(parent, operation)
preparation.Stock = stock
if err != nil {
return stock, err
return preparation, err
}
status = usableObservation(status, nil, operation)
started := c.now()
@@ -560,6 +574,13 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
var lastFC7, uncertainSince time.Time
var previous preparationClass
defer func() {
preparation.Stock = stock
preparation.ShakesUsed = shakes
preparation.lastFC7 = lastFC7
if resultErr == nil && !lastFC7.IsZero() {
class, _ := classifyPreparationStatus(status)
preparation.UncertainHandoff = class != encoderConfirmed
}
log.Infof("[%s] preparation finished; stage=%s shakes=%d elapsed=%s raw status: % X error=%v", operation, stage, shakes, c.now().Sub(started), status, resultErr)
}()
checkDeadline := func() error {
@@ -624,7 +645,7 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
for {
if err := checkDeadline(); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
class, _ := classifyPreparationStatus(status)
// No class means unusable telemetry, sharing the uncertainty timer.
@@ -634,41 +655,41 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
switch class {
case encoderConfirmed:
stage = "encoder sensor handoff"
return stock, observationResult(checkDeadline())
return preparation, observationResult(checkDeadline())
case positionWellEmpty:
stage = "empty"
return stock, ErrCardWellEmpty
return preparation, ErrCardWellEmpty
}
if lastFC7.IsZero() {
if err := sendFC7(); err != nil {
return stock, err
return preparation, err
}
} else if class == positionNoCard && c.now().Sub(lastFC7) >= sequenceShakeAfter {
uncertainSince = time.Time{}
if shakes == sequenceMaxShakes {
stage = "three shakes exhausted"
return stock, ErrPreparationExhausted
return preparation, ErrPreparationExhausted
}
shakes++
stage = "RS dispatch"
if err := checkDeadline(); err != nil {
return stock, err
return preparation, err
}
err := c.Reset(ctx)
if deadlineErr := checkDeadline(); deadlineErr != nil {
return stock, deadlineErr
return preparation, deadlineErr
}
if err != nil {
return stock, fmt.Errorf("[%s] RS dispatch: %w", operation, err)
return preparation, fmt.Errorf("[%s] RS dispatch: %w", operation, err)
}
stage = "reset settling"
log.Infof("[%s] RS dispatched; shake=%d settling=%s", operation, shakes, sequenceResetWait)
if err := wait(sequenceResetWait); err != nil {
return stock, err
return preparation, err
}
log.Infof("[%s] reset settle wait completed; shake=%d", operation, shakes)
if err := sendFC7(); err != nil {
return stock, err
return preparation, err
}
} else {
if class == positionUncertain || class == "" {
@@ -677,26 +698,26 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
if c.now().Sub(uncertainSince) >= sequenceUncertainWait {
stage = "uncertain position handoff"
return stock, observationResult(checkDeadline())
return preparation, observationResult(checkDeadline())
}
} else {
uncertainSince = time.Time{}
}
stage = "polling"
if err := wait(sequencePollInterval); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
}
stage = "fresh AP"
if err := checkDeadline(); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
status, stock, err = c.readSequenceStatus(ctx, operation)
if deadlineErr := checkDeadline(); deadlineErr != nil {
return stock, observationResult(deadlineErr)
return preparation, observationResult(deadlineErr)
}
if err != nil {
return stock, err
return preparation, err
}
}
}
@@ -706,6 +727,80 @@ func (c *Client) PrepareCurrentCard(ctx context.Context) (string, error) {
return c.prepareCardAtEncoder(ctx, "PrepareCurrentCard")
}
// PrepareCurrentCardForEncoding preserves preparation while exposing uncertain handoff.
func (c *Client) PrepareCurrentCardForEncoding(ctx context.Context) (PreparationResult, error) {
return c.prepareCardForEncoding(ctx, "PrepareCurrentCard")
}
// RecoverCurrentCard spends only the remaining issuance budget during encoding.
// It must be cancelled and joined before delivery; all commands use the serial worker.
func (c *Client) RecoverCurrentCard(ctx context.Context, preparation PreparationResult) (resultErr error) {
if !preparation.UncertainHandoff {
return nil
}
const operation = "uncertain encoding recovery"
started := c.now()
shakes, lastFC7 := preparation.ShakesUsed, preparation.lastFC7
reason := "recovery error"
defer func() {
if ctx.Err() != nil {
reason = context.Cause(ctx).Error()
}
log.Infof("[%s] stopped; reason=%s shakes=%d remaining=%d elapsed=%s error=%v", operation, reason, shakes, sequenceMaxShakes-shakes, c.now().Sub(started), resultErr)
}()
log.Infof("[%s] started; shakes=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
observe := func() (bool, error) {
status, _, err := c.readSequenceStatus(ctx, operation)
if err != nil {
return true, err
}
class, _ := classifyPreparationStatus(status)
log.Infof("[%s] fresh AP; class=%s shakes=%d remaining=%d raw status: % X", operation, class, shakes, sequenceMaxShakes-shakes, status)
switch class {
case encoderConfirmed:
reason = "encoder confirmed"
return true, nil
case positionWellEmpty:
reason = "card well empty"
return true, ErrCardWellEmpty
default:
return false, nil
}
}
for {
if stopped, err := observe(); stopped {
return err
}
if shakes >= sequenceMaxShakes {
reason = "shake budget exhausted"
return nil
}
if remaining := sequenceShakeAfter - c.now().Sub(lastFC7); remaining > 0 {
if err := c.sequenceTiming.wait(ctx, min(sequencePollInterval, remaining)); err != nil {
return err
}
continue
}
shakes++
log.Infof("[%s] RS attempt; shake=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
if err := c.Reset(ctx); err != nil {
return fmt.Errorf("[%s] RS dispatch: %w", operation, err)
}
if err := c.sequenceTiming.wait(ctx, sequenceResetWait); err != nil {
return err
}
// A diagnostic AP cannot turn unusable telemetry into a fatal error.
if stopped, err := observe(); stopped {
return err
}
log.Infof("[%s] FC7 attempt; shake=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
if err := c.ToEncoder(ctx); err != nil {
return fmt.Errorf("[%s] FC7 dispatch: %w", operation, err)
}
lastFC7 = c.now()
}
}
// DeliverCurrentCard presents the encoded card and confirms command acceptance.
func (c *Client) DeliverCurrentCard(ctx context.Context) (string, error) {
const operation = "DeliverCurrentCard"