6426c0cacd
Phase 01: Semantic Position Model - Implementation decisions documented - Phase boundary established
69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# Phase 1: Semantic Position Model - Context
|
|
|
|
**Gathered:** 2026-01-18
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
All movable items have a persistent semantic position `(day: Int, sortOrder: Double)` that survives data reloads. Games are immovable anchors ordered by game time. Travel segments and custom items can be repositioned. This phase establishes the data model only — constraint validation, flattening, and drag interaction are separate phases.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### sortOrder assignment
|
|
- Use integer spacing (1, 2, 3...) for initial sortOrder values
|
|
- Midpoint insertion (1.5, 1.25, etc.) when placing between items
|
|
- Claude's discretion on threshold/rebalancing strategy when gaps get very small
|
|
- Claude's discretion on negative vs positive sortOrder for "before games" items
|
|
- Claude's discretion on Double vs Decimal storage type
|
|
|
|
### Day boundaries
|
|
- Day = trip day backed by calendar date (Day 1 = trip.startDate, Day 2 = startDate + 1, etc.)
|
|
- Day number derived as: `calendar_days_since(trip.startDate) + 1`
|
|
- Games belong to their start date, even if they run past midnight
|
|
- Show all days including empty ones (no skipping gaps in the trip)
|
|
|
|
### Travel segment identity
|
|
- Each travel segment has a unique UUID (not keyed by route)
|
|
- Same route (e.g., Chicago→Boston) can appear multiple times in a trip
|
|
- Travel carries: from city, to city, estimated distance, estimated duration
|
|
- Moving travel to different day just updates the day property (no recalculation)
|
|
|
|
### Position initialization
|
|
- Games get sortOrder assigned by Claude based on game time
|
|
- Auto-generated travel appears after the origin city's games
|
|
- Custom items added via "+" button on day headers, inserted at top of that day
|
|
- Claude's discretion on handling position updates when trip is edited
|
|
|
|
### Claude's Discretion
|
|
- Exact sortOrder rebalancing threshold and strategy
|
|
- Whether to use negative sortOrder or offset games to higher values for "before" positioning
|
|
- Double vs Decimal for sortOrder storage
|
|
- Initial sortOrder derivation for games (time-based or sequential)
|
|
- Position preservation vs recomputation on trip edits
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Day headers should have a "+" button for adding custom items
|
|
- When user taps "+", item is added to top of that day (lowest sortOrder)
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-semantic-position-model*
|
|
*Context gathered: 2026-01-18*
|