Matching workouts to recorded activities

What "matching" means

A planned workout lives on the calendar. A recorded activity is what the athlete actually uploaded (a FIT, TCX, or GPX file). Matching them ties the two together so you can compare planned-vs-actual on the workout detail page.

How auto-match works

When an athlete uploads an Activity, the Hub runs the auto-matcher:

1. Look for planned workouts on the same date with the same sport.
2. Skip workouts already matched, or with match_locked set (user explicitly decided).
3. If multiple candidates exist, pick the one with the closest planned duration to the activity's actual duration.
4. Attach the activity, set status to completed.

The auto-matcher never overrides a manual decision and never matches across dates.

When auto-match gets it wrong

Common failure cases:

• The athlete did two runs on the same day. One was the planned one, the other was a recovery run. The auto-matcher picked the closer duration; if it picked wrong, manually unmatch and re-match.
• The athlete did the prescribed run a day late. The Hub will not auto-match across dates. Drag the planned workout to the correct date, then re-upload (or manually match).
• An athlete uploaded the wrong file. The match is bound to whatever file was uploaded. If the file is wrong, unmatch and re-upload the right one.

Manual match / unmatch

From the workout detail page (/athlete/<pid>/workout/<id>/):

• Unmatch: click the "Unmatch" button under the matched activity. This clears the link and locks the workout so auto-match will not re-attach a fresh activity. Status reverts to planned.
• Match to a different activity: from the activity detail page, manually attach an activity to a planned workout. (UI for this lands in Phase 1.1; for now, unmatch the wrong one and the next upload will auto-match.)

What "match locked" means

When you manually match or unmatch, the workout gets match_locked=True. This tells the auto-matcher to leave it alone. If you later want auto-match to consider it again, edit the workout from admin and clear the flag.

Why no cross-date auto-match

The system deliberately does not match a Tuesday Activity to a Wednesday planned workout. The risks (matching the wrong day, getting taper or recovery decisions wrong) are larger than the convenience. The fix is to drag the planned workout to the correct date first.

See also: Calendar overview, Drag and drop in the calendar, Workout notes (three kinds).