Repository navigation
Description
Status: done
Part of workstream 4 of #3000.
TL;DR
Goal: The routing package has 10 profiles, two for each activity, and each client offers only these.
Problem: The package has 17 profiles. Each profile has its own cost columns, and with the hierarchy of #3227 its own cost tables, so each profile costs bake time, disk and server memory. The owner does not want 7 of them: the five shorter profiles, and less-climbing for the mountain bike and for hiking.
Decision:
- The profiles are
touring,touring/less-climbing,road,road/less-climbing,gravel,gravel/less-climbing,mtb,mtb/technical,hikingandhiking/alpine. The rule is two profiles for each activity (owner decision). No cost weight of a profile that stays changes. - An alternatives request offers the
less-climbingprofile of the activity only when that route has clearly less climb, with the reasonless_climbing. The reasonsshorterandsmoothergo. The reasons are thenprimary,less_climbingandcorridor. - So only a request with
touring,roadorgravelcan get a route of another profile. A request with aless-climbingprofile, withmtb,mtb/technical,hikingorhiking/alpinegets the routes through other places (corridor) only. The owner accepts this until the alternatives get their new design (workstream 5 of EPIC — Scale readiness: 100 concurrent users, long routes, from one region to the world #3000). - A plan stores a preset title. When a plan has a preset that its activity does not have (an old plan with
Shorter, orLess climbingwith the mountain bike), each client usesBalanced. The plan stays readable. - The query model keeps its goal
shortest; the web planner maps it toBalanced. - The package format goes from 8 to 9. The manifest stores each profile, and a reader of this change cannot read an old manifest that has
road/shorter. With a new number, the follower refuses an old package before it starts the route service. (The first design kept format 8; the code review showed that the service would then start on an old package and fail.) - The planner screens do not change, beside the entries that go.
Rejected: hiking/less-climbingas a third hiking profile: the owner adds it later if riders miss it.mtb/technicalorhiking/alpineas an alternative of the base profile: it is a choice of skill, not a trade-off, and a pick would change the skill preset.- Keep the
Shortervariant of the road-bike costs in the code so that an old package still opens: no released package needs it. A package and its service are published together.
Systems: routing, web-planner, companion-ios
Contracts:specs/route-package.md(the format number),specs/route-api.md(the reasons, the profile ID text),specs/planner-plan.md(the preset titles),specs/obc-data.md(one sentence on the catalog profiles)
Size: M (3 systems, compatible contract changes, about 500 changed lines, most of them tests)
Facts
Engine and bake:
Profile::presets()is the only source of profiles (model.rs#L92). A loop makes{name}/shorterand{name}/less-climbingfor each of the five base profiles (model.rs#L150-L177).mtb/technicalandhiking/alpineare copies of their base profile with a higher difficulty limit (model.rs#L179-L184).- The road bike has its own cost model with the variants
Balanced,ShorterandLessClimbing(enum RoadBike, model.rs#L84-L89).Shorterhas two effects: no terrain penalty (cost.rs#L76-L81) and a turn cost of 30 in place of 90 (road_bike.rs#L168-L172). The variant has no other effect inroad_bike::way. - The bake takes the profile list from
[routing] profilesofdata/planner.toml. It fails withUnknown profile IDwhen a name is not a preset (step.rs#L34-L42). The list is an option of the step, so a new list gives a new key and each region bakes its routing again, with no change of a revision. - The route catalog needs
touring,road,gravel,mtb/technicalandhiking/alpine(catalog/mod.rs#L29). All five stay.specs/obc-data.mdnamesmtbandhikingthere, which is wrong today. - The manifest of a package stores each profile as JSON. A manifest with
road/shorterholds the variantShorter, so an engine without that variant does not open such a package. - An alternatives request asks for
{base}/shorterand{base}/less-climbingand skips a profile that the package does not have (alternatives.rs#L37-L42). The reason of such a route comes fromtradeoff, not from the profile name (alternatives.rs#L198-L215):shorterfirst, thenless_climbing, thensmoother. So without a change, aless-climbingroute can get the name "Shorter". Thecorridorroutes do not depend on the profiles. - A router keeps at most three prepared profiles (data.rs#L60). This change keeps the value.
Web planner:
presetTitlesmaps a profile suffix to a title:Balanced,Shorter,Less climbing,Technical,Alpine(riding-profiles.ts#L13).servedPresetsgives the titles whose profile the region lists; while the region is unknown, it gives every title but the two skill titles, for each activity.- A plan is valid only when its
presetis one of the titles (trip-validation.ts#L77). So without a rule, an old plan withShorterbecomes unreadable, and the library offers to delete it. The title is not checked against the activity:mtbwithLess climbingis valid and then fails with the route error "Profile mtb/less-climbing is not installed". profileId(trip)joins the activity and the suffix of the preset (routing.ts#L162-L165).- The query search maps the goal
shortesttoShorterand keeps the preset of the plan when a query sets the activity (search/actions.ts#L26-L30). The goal list is part of the query model contract (contract.json). - The names of the alternatives come from the reasons (route-options.ts#L14). The web client has no closed list of reasons.
Phone app:
RoutePreferencehasbalanced,shorter,lessClimbing,technical,alpine, andRouteOption.Reasonhasprimary,shorter,lessClimbing,smoother,corridor(PlannerService.swift#L50-L61, #L93). An unknown reason fails the whole options answer, so the engine and the app must agree.PlannerPreviewPreset.applies(to:)allowstechnicalonly formtbandalpineonly forhiking, and every other preset for every activity (PlannerPreviewModel.swift#L47-L64). A plan loads an unknown title asBalanced, but it does not check the activity (#L686).
No change is necessary in planner/service, the route catalog, specs/route-package.md, specs/route-catalog.md, the route answer vector and the public docs under docs/content.
Plan
planner/router/src/model.rs:Profile::presets()gives the 10 profiles. The variant loop makes onlyless-climbing, and only fortouring,gravelandroad.enum RoadBikelosesShorter.planner/router/src/cost.rs: theRoadBike::Shorterarm of the terrain penalty goes.data/planner.toml: the list has the 10 profiles; its comment keeps the five catalog profiles. These three files change in one commit, because the bake refuses a name that is not a preset.planner/router-build/src/road_bike.rs: the turn cost is 90 (0 on a roundabout) for each road profile.waythen does not read itsvariantparameter: remove the parameter and its argument inplanner/router-build/src/cost.rs. Change the tests ofroad_bike.rs,cost.rsandsuitability.rsthat nameShorteror a removed profile.planner/router/src/alternatives.rs: the request asks only for{base}/less-climbing.tradeoffkeeps only the climb test: the candidate must have no unknown height in either route and at leastmax(100 m, 10 %)less climb, and the reason isless_climbing. Else the candidate is dropped. The tests for another difficulty limit and for the request profile itself stay.planner/router-build/tests/routing.rs:an_out_and_back_trip_gets_alternatives_within_one_query_budgetgets a fixture whose alternative is atouring/less-climbingroute with less climb.route_goals_preserve_the_bikes_surface_suitabilityusesroad/less-climbingandgravel/less-climbing. No test asserts a profile count.specs/route-api.md:reasonisprimary,less_climbingorcorridor; the profile ID text namestouring/less-climbing,mtb/technicalandhiking/alpineas the second profiles.specs/planner-plan.md:presetisBalanced,Less climbing(touring,road,gravel),Technical(mtb) orAlpine(hiking); a reader usesBalancedfor a preset that the activity does not have.specs/obc-data.md: the catalog needsmtb/technicalandhiking/alpine.planner/router-build/README.md: 10 metrics, the road table and the paragraph on variants.builder/web/src/lib/planner/riding-profiles.ts: one table gives the preset titles of each activity (touring,road,gravel:Balanced,Less climbing;mtb:Balanced,Technical;hiking:Balanced,Alpine), andpresetTitleslosesshorter.servedPresetsgives the titles of the activity that the region serves. While the region is unknown, it gives the titles of the activity withoutTechnicalandAlpine, as today. A new function gives the preset of a plan: its own title when the activity has it, elseBalanced.profileIdandroutingKeyinrouting.ts, the preset thatTripBar.svelteshows, andsearch/actions.tsuse it. So a plan, a version, an undo step and an import all show and route the same preset, and the stored title is not rewritten at load. A change of the activity inTripBar.sveltealready takes the first preset of the new activity.trip-validation.tsaccepts each string as apreset: a writer stores one of the titles ofspecs/planner-plan.md, and a reader accepts any string and usesBalancedfor one that the activity does not have.search/actions.tsmapsshortesttoBalanced.route-options.tsloses the names ofshorterandsmoother.TripBar.svelteloses the icon branch ofShorter.- Web tests: change the cases that name a removed preset, profile or reason (
routing.test.ts,route-options.test.ts,plan-session.test.ts,trip-validation.test.ts,search/actions.test.ts, the stub region oftests/browser/planner/stubs.js). One case shows that a plan withShorter, and one withmtbandLess climbing, routes with the Balanced profile. companion-ios:RoutePreferenceandPlannerPreviewPresetloseshorter;RouteOption.Reasonlosesshorterandsmoother;applies(to:)allowslessClimbingonly fortouring,roadandgravel; the load of a plan usesBalancedwhen the preset does not apply to the activity;PlannerRouteOptions.swiftloses the two reason names. Change the tests that use.shorteras "a preset that is not Balanced" to.lessClimbing, and the hiking preset list.
Order of release: the new route service does not open a package that has road/shorter. So a region gets its new package and the new service in the same publish. The phone app fails a route options answer that has a reason it does not know, so a build of the app with this change needs a service with this change. No rider has the app yet, and the service is published first. The bake program must be built again after step 1: it embeds data/planner.toml.
Files
planner/router/src/model.rs,planner/router/src/cost.rs,planner/router/src/alternatives.rs: change (steps 1 and 3).planner/router-build/src/road_bike.rs,planner/router-build/src/cost.rs,planner/router-build/src/suitability.rs: change (step 2).planner/router-build/tests/routing.rs: change (step 4).data/planner.toml: change (step 1).planner/router/src/package.rs,specs/route-package.md,planner/service/README.md, and each reader list or fixture that states the routing format: change (format 9).specs/route-api.md,specs/planner-plan.md,specs/obc-data.md,planner/router-build/README.md: change (step 5).builder/web/src/lib/planner/riding-profiles.ts,routing.ts,trip-validation.ts,route-options.ts,search/actions.ts,builder/web/src/components/planner/TripBar.svelte: change (step 6).builder/web/src/lib/planner/routing.test.ts,route-options.test.ts,plan-session.test.ts,trip-validation.test.ts,search/actions.test.ts,builder/web/tests/browser/planner/stubs.js: change (step 7).companion-ios/Packages/OBCKit/Sources/OBCPlanner/PlannerService.swift,Sources/OBCUI/PlannerPreview/PlannerPreviewModel.swift,Sources/OBCUI/PlannerPreview/PlannerRouteOptions.swift, and the testsPlannerServiceTests.swift,PlannerPreviewModelTests.swift,PlannerRouteOptionsTests.swift: change (step 8).
Public docs: none change.
Done when
obc test -p planner-routerandobc test -p planner-router-buildpass, and clippy is clean for both.- The planner suite of the web builder passes (the command of
builder/web/src/components/planner/README.md). - The iOS unit tests pass in CI.
- A bake of
central-switzerlandgives a package whoseGET /v1/regionlists the 10 profiles. - Owner: the planner offers two presets for each activity. A plan that was saved with
Shorteropens and routes asBalanced. The route options of a touring route show "Less climbing" and the routes through other places, and no "Shorter".
Out of scope
- The cost weights of the profiles and their tuning.
- A new view or a new method for alternatives (workstream 5 of EPIC — Scale readiness: 100 concurrent users, long routes, from one region to the world #3000).
- The goal list of the query model.
Generated by Claude Code
Activity