{"components":{"responses":{"PlanningError":{"content":{"application/json":{"example":{"error":"Generate the first plan before rerouting"},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid planning input, infeasible/unfinished search, failed output validation or Google Maps error."},"ServerError":{"content":{"application/json":{"example":{"error":"Unexpected server failure. Check the Flask terminal for details."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unexpected server error; details logged in Flask terminal."}},"schemas":{"ActivityBatch":{"properties":{"batch_id":{"type":"string"},"data_mode":{"enum":["demo","reviewed","user_targets"],"type":"string"},"generated_mdo_count":{"type":"integer"},"generation_policy":{"additionalProperties":true,"type":"object"},"mdo_count":{"type":"integer"},"mdos":{"items":{"$ref":"#/components/schemas/GeneratedMDOSummary"},"type":"array"},"notice":{"type":"string"},"production_ready":{"type":"boolean"},"record_count":{"type":"integer"},"requires_step4_validation":{"type":"boolean"},"route_feasibility":{"enum":["not_evaluated"],"type":"string"},"selection":{"properties":{"crop_ids":{"items":{"nullable":true,"type":"integer"},"type":"array"},"crops":{"items":{"$ref":"#/components/schemas/Crop"},"type":"array"},"end_date":{"format":"date","type":"string"},"season":{"$ref":"#/components/schemas/Season"},"season_id":{"nullable":true,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"type":"object"},"source_data_reviewed":{"type":"boolean"},"stage":{"enum":["generated_activity_records"],"type":"string"},"tbm":{"$ref":"#/components/schemas/MasterTBM"},"time_budget":{"properties":{"activity_budget_min":{"nullable":true,"type":"integer"},"travel_reserve_min":{"nullable":true,"type":"integer"},"workday_min":{"type":"integer"}},"type":"object"}},"required":["batch_id","tbm","selection","generation_policy","data_mode","production_ready","mdo_count","generated_mdo_count","record_count","mdos","route_feasibility","requires_step4_validation","time_budget","stage","notice"],"type":"object"},"ActivityCatalog":{"additionalProperties":{"$ref":"#/components/schemas/ActivityRule"},"type":"object"},"ActivityPeriodTarget":{"additionalProperties":false,"properties":{"acre_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activity_id":{"type":"string"},"activity_target":{"minimum":0,"type":"integer"},"farmer_target":{"minimum":0,"type":"integer"}},"required":["activity_id","activity_target","farmer_target","acre_target"],"type":"object"},"ActivityRule":{"properties":{"duration_min":{"type":"integer"},"farmer_max":{"nullable":true,"type":"integer"},"farmer_min":{"nullable":true,"type":"integer"},"name":{"type":"string"}},"required":["name","duration_min"],"type":"object"},"Algorithm":{"enum":["ortools","alns"],"type":"string"},"ArchiveTargetRequest":{"additionalProperties":false,"properties":{"expected_revision":{"minimum":1,"type":"integer"}},"required":["expected_revision"],"type":"object"},"CompareRequest":{"properties":{"seconds":{"default":10,"description":"Search budget per engine, excluding Google requests and validation overhead.","maximum":60,"minimum":0.5,"type":"number"}},"type":"object"},"Comparison":{"properties":{"comparison_notice":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/ComparisonResult"},"type":"array"},"seconds_per_engine":{"type":"number"},"travel_data_quality":{"type":"string"}},"required":["results","comparison_notice"],"type":"object"},"ComparisonResult":{"properties":{"algorithm":{"$ref":"#/components/schemas/Algorithm"},"data_quality":{"type":"string"},"error":{"type":"string"},"metrics":{"$ref":"#/components/schemas/Metrics"},"ok":{"type":"boolean"},"runtime_seconds":{"type":"number"},"search_stats":{"nullable":true,"type":"object"},"solver_status":{"type":"string"},"validation":{"$ref":"#/components/schemas/Validation"}},"required":["algorithm","ok","runtime_seconds"],"type":"object"},"Config":{"properties":{"activity_availability":{"type":"string"},"algorithms":{"items":{"$ref":"#/components/schemas/Algorithm"},"type":"array"},"browser_key":{"description":"Public browser Maps key; backend key is never returned.","type":"string"},"constraints":{"$ref":"#/components/schemas/InputConstraints"},"default_algorithm":{"$ref":"#/components/schemas/Algorithm"},"has_server_key":{"type":"boolean"},"mdo":{"$ref":"#/components/schemas/MDO"},"sample_notice":{"type":"string"},"start_date":{"format":"date","type":"string"}},"required":["browser_key","has_server_key","mdo","constraints","algorithms","default_algorithm"],"type":"object"},"CoordinateOverride":{"properties":{"id":{"description":"HQ or an existing village ID, e.g. V3.","type":"string"},"lat":{"maximum":37,"minimum":8,"type":"number"},"lon":{"maximum":98,"minimum":68,"type":"number"}},"required":["id","lat","lon"],"type":"object"},"Crop":{"description":"Workbook mapping record; use (season_id, crop_id) as the key. Crop IDs are reused across seasons, and names can occur under multiple IDs.","example":{"crop_id":28,"crop_name":"Apple","season_id":1},"properties":{"crop_id":{"type":"integer"},"crop_name":{"type":"string"},"season_id":{"type":"integer"}},"required":["crop_id","crop_name","season_id"],"type":"object"},"CropList":{"properties":{"count":{"type":"integer"},"crops":{"items":{"$ref":"#/components/schemas/Crop"},"type":"array"},"season":{"$ref":"#/components/schemas/Season"}},"required":["season","crops","count"],"type":"object"},"DayPlan":{"properties":{"acre_target":{"minimum":0,"type":"number"},"activity_entries":{"type":"integer"},"activity_rows":{"type":"integer"},"date":{"format":"date","type":"string"},"distance_km":{"type":"number"},"end_time":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"farmer_target":{"type":"integer"},"overtime_min":{"minimum":0,"type":"integer"},"road_geometry":{"$ref":"#/components/schemas/RoadGeometry"},"route_geometry_error":{"type":"string"},"route_points":{"items":{"$ref":"#/components/schemas/Point"},"type":"array"},"service_min":{"type":"integer"},"stops":{"items":{"$ref":"#/components/schemas/Stop"},"type":"array"},"travel_min":{"type":"integer"},"village_visits":{"type":"integer"}},"required":["date","stops","route_points","travel_min","service_min","distance_km","end_time","activity_rows","village_visits"],"type":"object"},"EmptyRequest":{"properties":{},"type":"object"},"Error":{"properties":{"error":{"type":"string"}},"required":["error"],"type":"object"},"GenerateActivitiesRequest":{"description":"Current target-driven mode requires target_plan_id. The older selection/generation shape applies only to legacy fixtures/installations.","oneOf":[{"additionalProperties":false,"properties":{"crop_ids":{"items":{"nullable":true,"type":"integer"},"minItems":1,"type":"array","uniqueItems":true},"end_date":{"format":"date","type":"string"},"generation":{"$ref":"#/components/schemas/GenerationOptions"},"season_id":{"nullable":true,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"required":["tbm_id","season_id","crop_ids","start_date","end_date"],"type":"object"},{"$ref":"#/components/schemas/GenerateTargetActivitiesRequest"}]},"GenerateTargetActivitiesRequest":{"additionalProperties":false,"properties":{"target_plan_id":{"type":"string"}},"required":["target_plan_id"],"type":"object"},"GeneratedActivity":{"description":"One independent record. Duration applies once, not 100 times. Dates remain unassigned until Step 4.","properties":{"acre_target":{"minimum":0,"type":"number"},"activity":{"type":"string"},"activity_id":{"type":"string"},"activity_target":{"type":"integer"},"assigned_date":{"format":"date","nullable":true,"type":"string"},"available_dates":{"items":{"format":"date","type":"string"},"type":"array"},"batch_id":{"type":"string"},"crop":{"type":"string"},"crop_id":{"type":"integer"},"duration_min":{"type":"integer"},"farmer_target":{"type":"integer"},"geography_id":{"type":"string"},"id":{"type":"string"},"pincode":{"type":"string"},"season":{"type":"string"},"season_id":{"type":"integer"},"status":{"type":"string"},"synthetic_holidays":{"type":"boolean"},"target_mode":{"type":"string"},"tbm_id":{"type":"string"},"village_code":{"type":"string"},"village_id":{"type":"string"},"village_name":{"type":"string"}},"required":["id","tbm_id","geography_id","village_id","village_code","crop_id","season_id","activity_id","duration_min","activity_target","farmer_target","acre_target","available_dates","assigned_date","synthetic_holidays"],"type":"object"},"GeneratedActivityPage":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/GeneratedActivity"},"type":"array"},"batch_id":{"type":"string"},"count":{"type":"integer"},"geography_id":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"},"requires_step4_validation":{"type":"boolean"},"summary":{"$ref":"#/components/schemas/GeneratedMDOSummary"},"tbm_id":{"type":"string"},"total":{"type":"integer"}},"required":["batch_id","tbm_id","geography_id","summary","requires_step4_validation","activities","count","total","limit","offset"],"type":"object"},"GeneratedMDOSummary":{"properties":{"activity_counts":{"additionalProperties":{"type":"integer"},"type":"object"},"candidate_village_count":{"type":"integer"},"crop_counts":{"additionalProperties":{"type":"integer"},"type":"object"},"eligible_village_count":{"type":"integer"},"geography_id":{"type":"string"},"issues":{"items":{"$ref":"#/components/schemas/MasterIssue"},"type":"array"},"mdo_name":{"type":"string"},"ready_for_step4":{"type":"boolean"},"record_count":{"type":"integer"},"records_url":{"type":"string"},"route_input_issues":{"items":{"$ref":"#/components/schemas/MasterIssue"},"type":"array"},"selected_village_count":{"type":"integer"},"status":{"enum":["generated","blocked"],"type":"string"},"unused_selected_crop_ids":{"items":{"type":"integer"},"type":"array"},"warnings":{"items":{"$ref":"#/components/schemas/MasterIssue"},"type":"array"},"workload_check":{"properties":{"max_activities_per_bin":{"type":"integer"},"max_service_minutes_per_bin":{"type":"integer"},"max_villages_per_bin":{"type":"integer"},"service_minutes":{"type":"integer"},"working_day_count":{"type":"integer"}},"type":"object"}},"required":["geography_id","mdo_name","status","record_count","ready_for_step4","issues","route_input_issues","warnings","records_url","workload_check"],"type":"object"},"GenerationOptions":{"additionalProperties":false,"properties":{"activity_minutes_per_workday":{"default":300,"maximum":480,"minimum":1,"type":"integer"},"mode":{"default":"demo","enum":["demo","strict"],"type":"string"},"seed":{"default":42,"maximum":2147483647,"minimum":0,"type":"integer"}},"type":"object"},"GeocodeCandidate":{"properties":{"accepted":{"type":"boolean"},"formatted_address":{"type":"string"},"lat":{"type":"number"},"location_type":{"type":"string"},"lon":{"type":"number"},"name":{"type":"string"},"partial_match":{"type":"boolean"},"point":{"type":"string"},"reason":{"type":"string"}},"required":["point","name","accepted"],"type":"object"},"GeocodeReport":{"properties":{"notice":{"type":"string"},"plan_reset":{"type":"boolean"},"results":{"items":{"$ref":"#/components/schemas/GeocodeCandidate"},"type":"array"}},"required":["results","plan_reset","notice"],"type":"object"},"InputConstraints":{"properties":{"days":{"maximum":366,"minimum":1,"type":"integer"},"max_activities_per_day":{"type":"integer"},"max_unique_villages_per_day":{"type":"integer"},"village_visit_frequency_days":{"type":"integer"},"workday_end":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"workday_start":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"}},"type":"object"},"MDO":{"properties":{"geography_id":{"type":"string"},"headquarters_coordinate_status":{"type":"string"},"headquarters_name":{"type":"string"},"hq_lat":{"type":"number"},"hq_lon":{"type":"number"},"name":{"type":"string"}},"required":["name","geography_id","hq_lat","hq_lon"],"type":"object"},"MasterActivity":{"properties":{"activity_id":{"type":"string"},"duration_min":{"minimum":1,"type":"integer"},"farmer_max":{"nullable":true,"type":"integer"},"farmer_min":{"nullable":true,"type":"integer"},"name":{"type":"string"},"remarks":{"type":"string"}},"required":["activity_id","name","duration_min"],"type":"object"},"MasterActivityList":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/MasterActivity"},"type":"array"},"count":{"nullable":true,"type":"integer"}},"required":["activities","count"],"type":"object"},"MasterError":{"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"error":{"type":"string"}},"required":["error","code","details"],"type":"object"},"MasterHolidayCalendar":{"properties":{"covers_full_year":{"type":"boolean"},"holidays":{"items":{"properties":{"date":{"format":"date","type":"string"},"name":{"type":"string"},"scope":{"enum":["national","state","business_approved_optional","demo"],"type":"string"}},"required":["date","name","scope"],"type":"object"},"type":"array"},"source":{"type":"string"},"state_code":{"type":"string"},"status":{"type":"string"},"year":{"nullable":true,"type":"integer"}},"required":["year","state_code","status","source","covers_full_year","holidays"],"type":"object"},"MasterHolidayCatalog":{"properties":{"calendars":{"items":{"properties":{"covers_full_year":{"type":"boolean"},"source":{"type":"string"},"state_code":{"type":"string"},"status":{"type":"string"},"year":{"nullable":true,"type":"integer"}},"type":"object"},"type":"array"},"count":{"nullable":true,"type":"integer"},"status":{"type":"string"}},"required":["status","calendars","count"],"type":"object"},"MasterIssue":{"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"MasterMDO":{"properties":{"coordinate_availability":{"enum":["available","missing","invalid","expired"],"type":"string"},"coordinate_expires_at":{"nullable":true,"type":"string"},"coordinate_fetched_at":{"nullable":true,"type":"string"},"coordinate_reference":{"nullable":true,"type":"string"},"coordinate_source":{"nullable":true,"type":"string"},"coordinate_status":{"nullable":true,"type":"string"},"coordinate_verified":{"type":"boolean"},"coordinate_verified_at":{"nullable":true,"type":"string"},"district":{"nullable":true,"type":"string"},"geography_id":{"type":"string"},"geography_name":{"type":"string"},"headquarters":{"type":"string"},"hq_lat":{"nullable":true,"type":"number"},"hq_lon":{"nullable":true,"type":"number"},"mapping_status":{"type":"string"},"name":{"type":"string"},"state_code":{"nullable":true,"type":"string"},"state_name":{"nullable":true,"type":"string"},"state_resolution":{"nullable":true,"type":"string"},"state_source":{"nullable":true,"type":"string"},"tbm_id":{"type":"string"},"village_count":{"nullable":true,"type":"integer"}},"required":["tbm_id","geography_id","name","hq_lat","hq_lon","coordinate_availability","coordinate_verified"],"type":"object"},"MasterMDOList":{"properties":{"count":{"nullable":true,"type":"integer"},"limit":{"nullable":true,"type":"integer"},"mdos":{"items":{"$ref":"#/components/schemas/MasterMDO"},"type":"array"},"offset":{"nullable":true,"type":"integer"},"tbm":{"$ref":"#/components/schemas/MasterTBM"},"total":{"nullable":true,"type":"integer"}},"required":["tbm","mdos","count","total","limit","offset"],"type":"object"},"MasterPlanningInputs":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/MasterActivity"},"type":"array"},"calendars":{"additionalProperties":{"$ref":"#/components/schemas/MasterWorkingDays"},"type":"object"},"mdo_count":{"nullable":true,"type":"integer"},"mdos":{"items":{"properties":{"available_coordinate_village_count":{"nullable":true,"type":"integer"},"calendar_key":{"nullable":true,"type":"string"},"issues":{"items":{"$ref":"#/components/schemas/MasterIssue"},"type":"array"},"mdo":{"$ref":"#/components/schemas/MasterMDO"},"production_ready":{"type":"boolean"},"ready":{"type":"boolean"},"verified_coordinate_village_count":{"nullable":true,"type":"integer"},"village_count":{"nullable":true,"type":"integer"},"villages_url":{"type":"string"},"warnings":{"items":{"$ref":"#/components/schemas/MasterIssue"},"type":"array"}},"required":["mdo","village_count","calendar_key","ready","issues","villages_url"],"type":"object"},"type":"array"},"next_step":{"type":"string"},"ready":{"type":"boolean"},"ready_mdo_count":{"nullable":true,"type":"integer"},"selection":{"properties":{"crop_ids":{"items":{"nullable":true,"type":"integer"},"type":"array"},"crops":{"items":{"$ref":"#/components/schemas/Crop"},"type":"array"},"end_date":{"format":"date","type":"string"},"season":{"$ref":"#/components/schemas/Season"},"season_id":{"nullable":true,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"type":"object"},"settings":{"$ref":"#/components/schemas/MasterSettings"},"stage":{"enum":["validated_master_inputs"],"type":"string"},"tbm":{"$ref":"#/components/schemas/MasterTBM"}},"required":["tbm","selection","settings","activities","mdos","mdo_count","ready_mdo_count","ready","calendars","stage","next_step"],"type":"object"},"MasterPlanningSelection":{"additionalProperties":false,"properties":{"crop_ids":{"items":{"nullable":true,"type":"integer"},"minItems":1,"type":"array","uniqueItems":true},"end_date":{"format":"date","type":"string"},"season_id":{"nullable":true,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"required":["tbm_id","season_id","crop_ids","start_date","end_date"],"type":"object"},"MasterSettings":{"description":"Prepared master settings: Monday=0 through Saturday=5; 100/100/100 per generated record. Duration applies once per record. Six activities is a maximum, not a target.","properties":{"acre_target":{"nullable":true,"type":"integer"},"activity_target":{"nullable":true,"type":"integer"},"allow_fresh_centres_for_demo":{"type":"boolean"},"calendar_mode":{"type":"string"},"duration_basis":{"type":"string"},"enforce_master_farmer_ranges_in_demo":{"type":"boolean"},"farmer_target":{"nullable":true,"type":"integer"},"geographic_eligibility":{"type":"string"},"max_activities_per_day":{"nullable":true,"type":"integer"},"max_unique_villages_per_day":{"nullable":true,"type":"integer"},"missing_holiday_calendar_policy":{"type":"string"},"target_mode":{"type":"string"},"target_scope":{"type":"string"},"timezone":{"type":"string"},"vacant_mdo_policy":{"type":"string"},"workday_end":{"type":"string"},"workday_start":{"type":"string"},"working_weekdays":{"items":{"nullable":true,"type":"integer"},"type":"array"}},"required":["activity_target","farmer_target","acre_target","working_weekdays","max_activities_per_day"],"type":"object"},"MasterTBM":{"properties":{"name":{"type":"string"},"tbm_id":{"type":"string"}},"required":["tbm_id","name"],"type":"object"},"MasterTBMList":{"properties":{"count":{"nullable":true,"type":"integer"},"limit":{"nullable":true,"type":"integer"},"offset":{"nullable":true,"type":"integer"},"tbms":{"items":{"properties":{"excluded_vacant_mdo_count":{"nullable":true,"type":"integer"},"excluded_village_count":{"nullable":true,"type":"integer"},"mdo_count":{"nullable":true,"type":"integer"},"name":{"type":"string"},"tbm_id":{"type":"string"},"village_count":{"nullable":true,"type":"integer"}},"type":"object"},"type":"array"},"total":{"nullable":true,"type":"integer"}},"required":["tbms","count","total","limit","offset"],"type":"object"},"MasterVillage":{"properties":{"coordinate_availability":{"enum":["available","missing","invalid","expired"],"type":"string"},"coordinate_expires_at":{"nullable":true,"type":"string"},"coordinate_fetched_at":{"nullable":true,"type":"string"},"coordinate_reference":{"nullable":true,"type":"string"},"coordinate_source":{"nullable":true,"type":"string"},"coordinate_status":{"nullable":true,"type":"string"},"coordinate_verified":{"type":"boolean"},"coordinate_verified_at":{"nullable":true,"type":"string"},"district":{"nullable":true,"type":"string"},"geography_id":{"type":"string"},"lat":{"nullable":true,"type":"number"},"lon":{"nullable":true,"type":"number"},"name":{"type":"string"},"pincode":{"type":"string"},"state_code":{"nullable":true,"type":"string"},"state_name":{"nullable":true,"type":"string"},"state_resolution":{"nullable":true,"type":"string"},"state_source":{"nullable":true,"type":"string"},"tbm_id":{"type":"string"},"village_code":{"type":"string"}},"required":["geography_id","village_code","name","pincode","lat","lon","coordinate_availability","coordinate_verified"],"type":"object"},"MasterVillageList":{"properties":{"count":{"nullable":true,"type":"integer"},"geography_id":{"type":"string"},"limit":{"nullable":true,"type":"integer"},"offset":{"nullable":true,"type":"integer"},"tbm_id":{"type":"string"},"total":{"nullable":true,"type":"integer"},"villages":{"items":{"$ref":"#/components/schemas/MasterVillage"},"type":"array"}},"required":["tbm_id","geography_id","villages","count","total","limit","offset"],"type":"object"},"MasterWorkingDays":{"properties":{"calendar_day_count":{"nullable":true,"type":"integer"},"calendar_mode":{"enum":["approved","demo"],"type":"string"},"end_date":{"format":"date","type":"string"},"excluded_dates":{"items":{"properties":{"date":{"format":"date","type":"string"},"holidays":{"items":{"type":"string"},"type":"array"},"reasons":{"items":{"enum":["weekly_off","public_holiday"],"type":"string"},"type":"array"}},"required":["date","reasons","holidays"],"type":"object"},"type":"array"},"start_date":{"format":"date","type":"string"},"state_code":{"type":"string"},"synthetic_holidays":{"type":"boolean"},"working_dates":{"items":{"format":"date","type":"string"},"type":"array"},"working_day_count":{"nullable":true,"type":"integer"}},"required":["state_code","start_date","end_date","calendar_day_count","working_dates","working_day_count","excluded_dates"],"type":"object"},"Metrics":{"properties":{"acre_target":{"type":"integer"},"days_with_work":{"type":"integer"},"distance_km":{"type":"number"},"farmer_target":{"type":"integer"},"scheduled_activities":{"type":"integer"},"service_min":{"type":"integer"},"total_visits":{"type":"integer"},"travel_min":{"type":"integer"}},"type":"object"},"MonthlyPlanRequest":{"additionalProperties":false,"properties":{"algorithm":{"default":"ortools","enum":["ortools","alns"],"type":"string"},"daily_requirement_scope":{"default":"full_month","enum":["full_month"],"type":"string"},"month":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"},"seconds":{"default":20,"maximum":60,"minimum":0.5,"type":"number"},"tbm_id":{"type":"string"},"traffic_mode":{"default":"sampled_average","enum":["sampled_average","traffic_unaware"],"type":"string"}},"required":["tbm_id","month"],"type":"object"},"OverrideResult":{"properties":{"notice":{"type":"string"},"ok":{"type":"boolean"}},"required":["ok","notice"],"type":"object"},"Plan":{"properties":{"algorithm":{"$ref":"#/components/schemas/Algorithm"},"batch_id":{"type":"string"},"completed_ids":{"items":{"type":"string"},"type":"array"},"constraints":{"additionalProperties":true,"type":"object"},"data_quality":{"type":"string"},"days":{"items":{"$ref":"#/components/schemas/DayPlan"},"type":"array"},"geography_id":{"type":"string"},"input_metadata":{"additionalProperties":true,"type":"object"},"maximum_workday_end":{"type":"string"},"mdo":{"$ref":"#/components/schemas/MDO"},"normal_workday_end":{"type":"string"},"objective_priority":{"items":{"type":"string"},"type":"array"},"overtime_min":{"minimum":0,"type":"integer"},"overtime_proven_minimal":{"type":"boolean"},"overtime_used":{"type":"boolean"},"planning_note":{"type":"string"},"production_ready":{"type":"boolean"},"replanned_from":{"properties":{"date":{"format":"date","type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"time":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"}},"type":"object"},"road_geometry_mode":{"enum":["request_selected_day"],"type":"string"},"search_stats":{"additionalProperties":true,"type":"object"},"solver_status":{"enum":["OPTIMAL","FEASIBLE","HEURISTIC_FEASIBLE"],"type":"string"},"target_coverage":{"type":"object"},"travel_profile":{"$ref":"#/components/schemas/RoadTravelProfile"},"unverified_prior_task_ids":{"items":{"type":"string"},"type":"array"},"validation":{"$ref":"#/components/schemas/Validation"}},"required":["algorithm","mdo","days","solver_status","data_quality","completed_ids","validation"],"type":"object"},"PlanRequest":{"properties":{"algorithm":{"default":"ortools","enum":["ortools","alns"],"type":"string"}},"type":"object"},"PlannerData":{"allOf":[{"$ref":"#/components/schemas/InputConstraints"},{"properties":{"demo":{"type":"boolean"},"geography_id":{"type":"string"},"geography_name":{"type":"string"},"mdo":{"$ref":"#/components/schemas/MDO"},"notes":{"items":{"type":"string"},"type":"array"},"start_date":{"format":"date","type":"string"},"tasks":{"items":{"$ref":"#/components/schemas/Task"},"type":"array"},"villages":{"items":{"$ref":"#/components/schemas/Village"},"type":"array"}},"required":["mdo","start_date","villages","tasks"],"type":"object"}]},"PlanningConstraints":{"properties":{"activity_types":{"items":{"properties":{"activity_id":{"type":"string"},"duration_min":{"minimum":1,"type":"integer"},"farmer_max":{"minimum":0,"nullable":true,"type":"integer"},"farmer_min":{"minimum":0,"nullable":true,"type":"integer"},"harvest_only":{"type":"boolean"},"max_per_day":{"minimum":0,"nullable":true,"type":"integer"},"min_gap_days":{"minimum":0,"type":"integer"},"min_per_day":{"minimum":0,"type":"integer"},"name":{"type":"string"},"rule_confirmation_required":{"type":"boolean"},"temporary_id":{"type":"boolean"}},"type":"object"},"type":"array"},"global":{"properties":{"holiday_policy":{"enum":["mdo_state"],"type":"string"},"max_activities_per_day":{"minimum":0,"nullable":true,"type":"integer"},"max_travel_km_per_day":{"minimum":0,"nullable":true,"type":"number"},"max_villages_per_day":{"minimum":0,"nullable":true,"type":"integer"},"max_work_minutes":{"example":600,"minimum":1,"type":"integer"},"normal_work_minutes":{"example":480,"minimum":1,"type":"integer"},"workday_start":{"example":"09:00","type":"string"},"working_weekdays":{"items":{"maximum":6,"minimum":0,"type":"integer"},"type":"array"}},"type":"object"},"revision":{"minimum":0,"type":"integer"},"source":{"type":"object"}},"required":["revision","global","activity_types"],"type":"object"},"PlanningConstraintsPatch":{"additionalProperties":false,"properties":{"activity_types":{"items":{"additionalProperties":false,"properties":{"activity_id":{"type":"string"},"duration_min":{"minimum":1,"type":"integer"},"farmer_max":{"minimum":0,"nullable":true,"type":"integer"},"farmer_min":{"minimum":0,"nullable":true,"type":"integer"},"harvest_only":{"type":"boolean"},"max_per_day":{"minimum":0,"nullable":true,"type":"integer"},"min_gap_days":{"minimum":0,"type":"integer"},"min_per_day":{"minimum":0,"type":"integer"},"name":{"type":"string"},"rule_confirmation_required":{"type":"boolean"},"temporary_id":{"type":"boolean"}},"required":["activity_id"],"type":"object"},"type":"array"},"expected_revision":{"minimum":1,"type":"integer"},"global":{"additionalProperties":false,"properties":{"holiday_policy":{"enum":["mdo_state"],"type":"string"},"max_activities_per_day":{"minimum":0,"nullable":true,"type":"integer"},"max_travel_km_per_day":{"minimum":0,"nullable":true,"type":"number"},"max_villages_per_day":{"minimum":0,"nullable":true,"type":"integer"},"max_work_minutes":{"example":600,"minimum":1,"type":"integer"},"normal_work_minutes":{"example":480,"minimum":1,"type":"integer"},"workday_start":{"example":"09:00","type":"string"},"working_weekdays":{"items":{"maximum":6,"minimum":0,"type":"integer"},"type":"array"}},"type":"object"}},"required":["expected_revision"],"type":"object"},"Point":{"properties":{"id":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"name":{"type":"string"}},"required":["id","lat","lon"],"type":"object"},"RerouteRequest":{"properties":{"algorithm":{"$ref":"#/components/schemas/Algorithm"},"completed_task_ids":{"default":[],"description":"Known task IDs actually completed, e.g. T01; not activity-master IDs.","items":{"type":"string"},"type":"array"},"current_time":{"default":"12:00","example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"date":{"format":"date","type":"string"},"lat":{"maximum":90,"minimum":-90,"type":"number"},"lon":{"maximum":180,"minimum":-180,"type":"number"}},"required":["date","lat","lon"],"type":"object"},"RoadComparisonOptions":{"additionalProperties":false,"properties":{"geography_ids":{"items":{"type":"string"},"type":"array"},"seconds":{"default":20,"description":"Solver budget per MDO per engine; Google/network time is additional.","maximum":60,"minimum":0.5,"type":"number"},"traffic_mode":{"default":"sampled_average","enum":["sampled_average","traffic_unaware"],"type":"string"}},"type":"object"},"RoadGeometry":{"nullable":true,"properties":{"encoded_polyline":{"type":"string"},"legs":{"items":{"properties":{"encoded_polyline":{"type":"string"},"kind":{"enum":["visit","return"],"type":"string"}},"required":["kind","encoded_polyline"],"type":"object"},"type":"array"},"road_distance_km":{"type":"number"},"road_travel_min":{"type":"integer"}},"required":["encoded_polyline","legs"],"type":"object"},"RoadGeometryRequest":{"additionalProperties":false,"properties":{"date":{"format":"date","type":"string"}},"required":["date"],"type":"object"},"RoadGeometryResponse":{"properties":{"date":{"format":"date","type":"string"},"geography_id":{"type":"string"},"job_id":{"type":"string"},"notice":{"type":"string"},"revision":{"type":"integer"},"road_geometry":{"nullable":true,"type":"object"}},"required":["job_id","geography_id","revision","date","road_geometry","notice"],"type":"object"},"RoadMDOJob":{"properties":{"comparison":{"description":"Per-engine results: ok, solver status, independent validation, metrics and runtime.","type":"object"},"error":{"nullable":true,"type":"object"},"geography_id":{"type":"string"},"mdo_name":{"type":"string"},"metrics":{"type":"object"},"plan_url":{"type":"string"},"revision":{"type":"integer"},"runtime_seconds":{"type":"number"},"solver_status":{"type":"string"},"state":{"enum":["queued","planning","planned","compared","blocked","failed","interrupted","staged","withheld","cancelled"],"type":"string"},"travel_profile":{"$ref":"#/components/schemas/RoadTravelProfile"}},"required":["geography_id","mdo_name","state","plan_url"],"type":"object"},"RoadMDOPlan":{"properties":{"geography_id":{"type":"string"},"job_id":{"type":"string"},"plan":{"$ref":"#/components/schemas/Plan"},"revision":{"type":"integer"}},"required":["job_id","geography_id","revision","plan"],"type":"object"},"RoadPlanningJob":{"properties":{"all_tbm_targets_planned":{"type":"boolean"},"batch_id":{"type":"string"},"counts":{"additionalProperties":{"type":"integer"},"type":"object"},"created_at":{"format":"date-time","type":"string"},"job_id":{"type":"string"},"kind":{"enum":["planning","comparison"],"type":"string"},"mdos":{"items":{"$ref":"#/components/schemas/RoadMDOJob"},"type":"array"},"month":{"type":"string"},"monthly":{"type":"boolean"},"options":{"$ref":"#/components/schemas/RoadPlanningOptions"},"plan_published":{"type":"boolean"},"state":{"enum":["queued","running","completed","partial","failed","blocked","interrupted","stale"],"type":"string"},"target_reconciliation":{"items":{"type":"object"},"type":"array"},"target_summaries":{"items":{"type":"object"},"type":"array"},"tbm":{"$ref":"#/components/schemas/MasterTBM"}},"required":["job_id","batch_id","tbm","state","kind","options","created_at","mdos","counts"],"type":"object"},"RoadPlanningOptions":{"additionalProperties":false,"properties":{"algorithm":{"default":"ortools","enum":["ortools","alns"],"type":"string"},"geography_ids":{"items":{"type":"string"},"type":"array"},"seconds":{"default":20,"description":"Solver budget per MDO per engine; Google/network time is additional.","maximum":60,"minimum":0.5,"type":"number"},"traffic_mode":{"default":"sampled_average","enum":["sampled_average","traffic_unaware"],"type":"string"}},"type":"object"},"RoadRerouteRequest":{"additionalProperties":false,"properties":{"algorithm":{"default":"ortools","enum":["ortools","alns"],"type":"string"},"completed_task_ids":{"items":{"type":"string"},"type":"array"},"current_time":{"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"date":{"format":"date","type":"string"},"expected_revision":{"minimum":1,"type":"integer"},"lat":{"maximum":90,"minimum":-90,"type":"number"},"lon":{"maximum":180,"minimum":-180,"type":"number"},"seconds":{"default":20,"description":"Solver budget per MDO per engine; Google/network time is additional.","maximum":60,"minimum":0.5,"type":"number"},"travelled_km_today":{"minimum":0,"type":"number"}},"required":["expected_revision","date","current_time","lat","lon","completed_task_ids"],"type":"object"},"RoadTravelProfile":{"properties":{"aggregation":{"type":"string"},"departure_times":{"items":{"format":"date-time","type":"string"},"type":"array"},"fallback_elements":{"type":"integer"},"mode":{"type":"string"},"notice":{"type":"string"},"representative_date":{"type":"string"},"routing_preference":{"type":"string"},"sampling_basis":{"type":"string"},"traffic_model":{"nullable":true,"type":"string"}},"type":"object"},"ScreenActivityDetail":{"properties":{"acreage_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activities_target":{"minimum":0,"type":"integer"},"activity_id":{"type":"string"},"activity_name":{"type":"string"},"duration_min":{"minimum":1,"nullable":true,"type":"integer"},"farmers_target":{"minimum":0,"type":"integer"}},"required":["activity_id","activity_name","duration_min","activities_target","farmers_target","acreage_target"],"type":"object"},"ScreenActivityInput":{"additionalProperties":false,"properties":{"acreage_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activities_target":{"minimum":0,"type":"integer"},"activity_id":{"type":"string"},"farmers_target":{"minimum":0,"type":"integer"}},"required":["activity_id","activities_target","farmers_target","acreage_target"],"type":"object"},"ScreenGeneratePlanRequest":{"additionalProperties":false,"properties":{"model_id":{"description":"model_a = Empower Model A / OR-Tools; model_b = Empower Model B / ALNS.","enum":["model_a","model_b"],"type":"string"},"month":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"},"seconds":{"default":20,"description":"Routing search budget per MDO, not a total HTTP or job deadline.","maximum":60,"minimum":0.5,"type":"number"},"tbl_id":{"description":"Existing tbm_id, named tbl_id by the frontend.","example":"local:gaurav-baliyan","type":"string"},"traffic_mode":{"default":"sampled_average","enum":["sampled_average","traffic_unaware"],"type":"string"}},"required":["tbl_id","month","model_id"],"type":"object"},"ScreenGenerationErrorDetail":{"nullable":true,"properties":{"code":{"type":"string"},"details":{"nullable":true,"type":"object"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"ScreenGenerationJob":{"properties":{"algorithm":{"enum":["ortools","alns"],"type":"string"},"error":{"$ref":"#/components/schemas/ScreenGenerationErrorDetail"},"job_id":{"description":"Copy from the Generate Plan response.","pattern":"^[0-9a-f]{32}$","type":"string"},"mdos":{"items":{"$ref":"#/components/schemas/ScreenMDOGenerationStatus"},"type":"array"},"model_id":{"description":"model_a = Empower Model A / OR-Tools; model_b = Empower Model B / ALNS.","enum":["model_a","model_b"],"type":"string"},"model_name":{"type":"string"},"month":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"},"plan_generated":{"description":"Show Plan Generated only when true: completed, published, all TBM targets planned.","type":"boolean"},"poll_after_ms":{"description":"Suggested polling interval: 1500 while active, 0 when terminal.","minimum":0,"type":"integer"},"progress":{"description":"Processed MDOs / total MDOs, not elapsed-time progress. Staged/failed/cancelled MDOs count as processed. Capped at 99 while the job is active. 100 alone does not mean success.","properties":{"percent":{"maximum":100,"minimum":0,"type":"integer"},"processed_mdos":{"minimum":0,"type":"integer"},"total_mdos":{"minimum":0,"type":"integer"}},"required":["processed_mdos","total_mdos","percent"],"type":"object"},"regeneration_required":{"type":"boolean"},"state":{"enum":["queued","running","completed","failed","blocked","interrupted","stale"],"type":"string"},"status_url":{"description":"Relative URL including job ID and tbl_id; GET to poll, without rerunning the model.","type":"string"},"tbl_id":{"description":"Existing tbm_id, named tbl_id by the frontend.","example":"local:gaurav-baliyan","type":"string"},"terminal":{"description":"True means stop polling; inspect plan_generated to distinguish success from failure.","type":"boolean"}},"required":["job_id","tbl_id","month","model_id","model_name","algorithm","state","plan_generated","terminal","progress","status_url","poll_after_ms","regeneration_required","mdos","error"],"type":"object"},"ScreenGenerationResponse":{"properties":{"data":{"$ref":"#/components/schemas/ScreenGenerationJob"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenMDOGenerationStatus":{"properties":{"error":{"$ref":"#/components/schemas/ScreenGenerationErrorDetail"},"geography_id":{"type":"string"},"mdo_name":{"type":"string"},"state":{"enum":["queued","planning","staged","planned","blocked","failed","withheld","cancelled","interrupted"],"type":"string"}},"required":["geography_id","mdo_name","state"],"type":"object"},"ScreenPlanningModel":{"properties":{"algorithm":{"enum":["ortools","alns"],"type":"string"},"model_id":{"description":"model_a = Empower Model A / OR-Tools; model_b = Empower Model B / ALNS.","enum":["model_a","model_b"],"type":"string"},"model_name":{"type":"string"}},"required":["model_id","model_name","algorithm"],"type":"object"},"ScreenPlanningModelsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ScreenPlanningModel"},"type":"array"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenTargetCards":{"properties":{"acreage_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activities_target":{"minimum":0,"type":"integer"},"farmers_target":{"minimum":0,"type":"integer"},"month":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"},"tbl_id":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"},"total_mdos":{"minimum":0,"type":"integer"},"total_targets":{"minimum":0,"type":"integer"}},"required":["tbl_id","month","total_mdos","total_targets","activities_target","farmers_target","acreage_target"],"type":"object"},"ScreenTargetCardsResponse":{"properties":{"data":{"$ref":"#/components/schemas/ScreenTargetCards"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenTargetDeleteResponse":{"properties":{"data":{"properties":{"revision":{"minimum":1,"type":"integer"},"target_id":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"}},"required":["target_id","revision"],"type":"object"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenTargetDetail":{"properties":{"acreage_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activities":{"items":{"$ref":"#/components/schemas/ScreenActivityDetail"},"type":"array"},"activities_target":{"minimum":0,"type":"integer"},"crop_id":{"minimum":0,"type":"integer"},"crop_name":{"type":"string"},"farmers_target":{"minimum":0,"type":"integer"},"from_date":{"format":"date","type":"string"},"revision":{"minimum":1,"type":"integer"},"season_id":{"minimum":0,"type":"integer"},"season_name":{"type":"string"},"target_id":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"},"tbl_id":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"},"to_date":{"format":"date","type":"string"}},"required":["target_id","tbl_id","season_id","season_name","crop_id","crop_name","from_date","to_date","activities_target","farmers_target","acreage_target","revision","activities"],"type":"object"},"ScreenTargetDetailResponse":{"properties":{"data":{"$ref":"#/components/schemas/ScreenTargetDetail"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenTargetEditInput":{"additionalProperties":false,"properties":{"activities":{"items":{"$ref":"#/components/schemas/ScreenActivityInput"},"minItems":1,"type":"array"},"crop_id":{"minimum":0,"type":"integer"},"expected_revision":{"minimum":1,"type":"integer"},"from_date":{"format":"date","type":"string"},"season_id":{"minimum":0,"type":"integer"},"tbl_id":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"},"to_date":{"format":"date","type":"string"}},"required":["tbl_id","season_id","crop_id","from_date","to_date","activities","expected_revision"],"type":"object"},"ScreenTargetError":{"properties":{"data":{"description":"Always null on errors.","nullable":true,"type":"object"},"error":{"properties":{"code":{"type":"string"},"details":{"nullable":true,"type":"object"}},"required":["code","details"],"type":"object"},"message":{"type":"string"},"status":{"enum":[false],"type":"boolean"}},"required":["status","message","data","error"],"type":"object"},"ScreenTargetInput":{"additionalProperties":false,"properties":{"activities":{"items":{"$ref":"#/components/schemas/ScreenActivityInput"},"minItems":1,"type":"array"},"crop_id":{"minimum":0,"type":"integer"},"from_date":{"format":"date","type":"string"},"season_id":{"minimum":0,"type":"integer"},"tbl_id":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"},"to_date":{"format":"date","type":"string"}},"required":["tbl_id","season_id","crop_id","from_date","to_date","activities"],"type":"object"},"ScreenTargetListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ScreenTargetRow"},"type":"array"},"message":{"type":"string"},"status":{"enum":[true],"type":"boolean"}},"required":["status","message","data"],"type":"object"},"ScreenTargetRow":{"properties":{"acreage_target":{"minimum":0,"multipleOf":0.01,"type":"number"},"activities_target":{"minimum":0,"type":"integer"},"crop_id":{"minimum":0,"type":"integer"},"crop_name":{"type":"string"},"farmers_target":{"minimum":0,"type":"integer"},"from_date":{"format":"date","type":"string"},"revision":{"minimum":1,"type":"integer"},"season_id":{"minimum":0,"type":"integer"},"season_name":{"type":"string"},"target_id":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"},"tbl_id":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"},"to_date":{"format":"date","type":"string"}},"required":["target_id","tbl_id","season_id","season_name","crop_id","crop_name","from_date","to_date","activities_target","farmers_target","acreage_target","revision"],"type":"object"},"Season":{"example":{"season_id":1,"season_name":"Kharif"},"properties":{"season_id":{"type":"integer"},"season_name":{"type":"string"}},"required":["season_id","season_name"],"type":"object"},"SeasonList":{"properties":{"count":{"type":"integer"},"seasons":{"items":{"$ref":"#/components/schemas/Season"},"type":"array"}},"required":["seasons","count"],"type":"object"},"Stop":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/Task"},"type":"array"},"arrival":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"duration_min":{"type":"integer"},"leave":{"example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"village":{"$ref":"#/components/schemas/Village"}},"required":["village","arrival","leave","duration_min","activities"],"type":"object"},"TargetPlan":{"properties":{"activity_targets":{"items":{"$ref":"#/components/schemas/ActivityPeriodTarget"},"type":"array"},"allocations":{"items":{"properties":{"activity_targets":{"items":{"$ref":"#/components/schemas/ActivityPeriodTarget"},"type":"array"},"geography_id":{"type":"string"},"mdo_name":{"type":"string"},"state_code":{"nullable":true,"type":"string"}},"type":"object"},"type":"array"},"created_at":{"type":"string"},"mdo_count":{"minimum":0,"type":"integer"},"month":{"type":"string"},"planning_scope":{"type":"string"},"revision":{"minimum":1,"type":"integer"},"route_feasibility":{"type":"string"},"selection":{"type":"object"},"stage":{"type":"string"},"status":{"enum":["active","archived"],"type":"string"},"target_plan_id":{"type":"string"},"tbm":{"$ref":"#/components/schemas/MasterTBM"},"totals":{"type":"object"}},"required":["target_plan_id","tbm","selection","activity_targets","allocations","mdo_count","totals"],"type":"object"},"TargetPlanEditRequest":{"additionalProperties":false,"properties":{"activity_targets":{"items":{"$ref":"#/components/schemas/ActivityPeriodTarget"},"type":"array"},"crop_id":{"minimum":0,"type":"integer"},"end_date":{"format":"date","type":"string"},"expected_revision":{"minimum":1,"type":"integer"},"season_id":{"minimum":0,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"required":["tbm_id","season_id","crop_id","start_date","end_date","activity_targets","expected_revision"],"type":"object"},"TargetPlanList":{"properties":{"count":{"minimum":0,"type":"integer"},"limit":{"minimum":0,"type":"integer"},"offset":{"minimum":0,"type":"integer"},"target_plans":{"items":{"$ref":"#/components/schemas/TargetPlanSummary"},"type":"array"},"total":{"minimum":0,"type":"integer"}},"type":"object"},"TargetPlanRequest":{"additionalProperties":false,"properties":{"activity_targets":{"items":{"$ref":"#/components/schemas/ActivityPeriodTarget"},"type":"array"},"crop_id":{"minimum":0,"type":"integer"},"end_date":{"format":"date","type":"string"},"season_id":{"minimum":0,"type":"integer"},"start_date":{"format":"date","type":"string"},"tbm_id":{"type":"string"}},"required":["tbm_id","season_id","crop_id","start_date","end_date","activity_targets"],"type":"object"},"TargetPlanSummary":{"properties":{"created_at":{"type":"string"},"mdo_count":{"minimum":0,"type":"integer"},"month":{"nullable":true,"type":"string"},"planning_scope":{"nullable":true,"type":"string"},"revision":{"minimum":1,"nullable":true,"type":"integer"},"selection":{"type":"object"},"stage":{"type":"string"},"status":{"enum":["active","archived"],"nullable":true,"type":"string"},"target_plan_id":{"type":"string"},"tbm":{"$ref":"#/components/schemas/MasterTBM"},"totals":{"type":"object"}},"type":"object"},"Task":{"properties":{"acre_target":{"minimum":0,"type":"number"},"activity":{"type":"string"},"activity_id":{"type":"string"},"activity_target":{"type":"integer"},"available_dates":{"items":{"format":"date","type":"string"},"type":"array"},"crop":{"type":"string"},"duration_min":{"type":"integer"},"earliest_date":{"format":"date","type":"string"},"farmer_target":{"type":"integer"},"id":{"type":"string"},"latest_date":{"format":"date","type":"string"},"season":{"type":"string"},"status":{"enum":["pending","completed","unverified (prior plan)"],"type":"string"},"unavailable_dates":{"items":{"format":"date","type":"string"},"type":"array"},"village_id":{"type":"string"}},"required":["id","village_id","activity_id","duration_min","activity_target","farmer_target","acre_target"],"type":"object"},"Validation":{"properties":{"errors":{"items":{"type":"string"},"type":"array"},"expected_outstanding":{"type":"integer"},"scheduled_task_count":{"type":"integer"},"valid":{"type":"boolean"}},"required":["valid","errors"],"type":"object"},"Village":{"properties":{"coordinate_source":{"type":"string"},"coordinate_status":{"type":"string"},"geography_id":{"type":"string"},"id":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"name":{"type":"string"},"pincode":{"type":"string"},"village_code":{"type":"string"}},"required":["id","name","lat","lon"],"type":"object"}}},"info":{"description":"One-MDO Flask PoC with OR-Tools CP-SAT and ALNS. Workflow: read reference data \u2192 generate plan \u2192 reroute as needed; compare engines independently. Try it out sends real requests to this server. POST operations can change shared in-memory state and call billable Google APIs. The demo has no authentication or per-user isolation. Original demo operations use TRAFFIC_UNAWARE; Step-4 Road planning supports representative traffic averages. Request schemas document the contract; they do not add runtime validation. Unexpected malformed input may still return 500. Prepared-master endpoints under /api/master-data serve the Step-1 snapshots. They perform runtime parameter/selection validation and report readiness; task arrangement is Step 3 and route optimization is Step 4. Step-3 activity batches are reproducible and stored locally. They are not dated/road-optimized plans. Step-4 jobs optimize generated records using Google road times. The existing single-MDO demo remains separate. Monthly generation combines active targets and publishes only on exact complete coverage.","title":"MDO Activity & Route Planner API","version":"6.2.0"},"openapi":"3.0.3","paths":{"/api/activity-master":{"get":{"description":"Original demo dictionary keyed by activity ID. Updated Step-1 durations are served at /api/master-data/activities.","operationId":"getActivityMaster","responses":{"200":{"content":{"application/json":{"example":{"24":{"duration_min":30,"farmer_max":50,"farmer_min":10,"name":"Field Day"},"25":{"duration_min":15,"farmer_max":50,"farmer_min":10,"name":"Harvest Days"},"27":{"duration_min":10,"farmer_max":150,"farmer_min":30,"name":"Branded Van Campaign(BVC/HVC)"},"28":{"duration_min":40,"farmer_max":100,"farmer_min":30,"name":"Large Farmer Meetings"},"36":{"duration_min":5,"farmer_max":5,"farmer_min":1,"name":"Attended to Customer Complaint"},"37":{"duration_min":10,"farmer_max":null,"farmer_min":null,"name":"Kisan Mela"},"38":{"duration_min":30,"farmer_max":100,"farmer_min":30,"name":"Product StewardShip Day"},"39":{"duration_min":10,"farmer_max":null,"farmer_min":null,"name":"Retailer contacts"},"40":{"duration_min":5,"farmer_max":null,"farmer_min":null,"name":"Review Meeting(BRM)"},"45":{"duration_min":60,"farmer_max":500,"farmer_min":100,"name":"Mega  Farmer Meetings"},"79":{"duration_min":5,"farmer_max":10,"farmer_min":1,"name":"Demo"},"89":{"duration_min":2,"farmer_max":null,"farmer_min":null,"name":"Mavilon FD/HD Plan"}},"schema":{"$ref":"#/components/schemas/ActivityCatalog"}}},"description":"Successful response"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Read original demo activity durations","tags":["Reference data"]}},"/api/compare":{"post":{"description":"Runs both engines on the original full input and one shared road matrix. Does not overwrite the active plan/completions or fetch route polylines. A 200 response may contain an individual engine with ok=false and an error. This is a fresh-plan benchmark, not a benchmark of the current reroute context.","operationId":"compareAlgorithms","requestBody":{"content":{"application/json":{"examples":{"Default budget":{"value":{"seconds":10}}},"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Compare OR-Tools and ALNS","tags":["Planning"]}},"/api/config":{"get":{"description":"Returns current limits, selected MDO, available engines and the public browser-key configuration.","operationId":"getConfig","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Config"}}},"description":"Successful response"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Read app configuration","tags":["Reference data"]}},"/api/crops":{"get":{"description":"Requires exactly one season_id from GET /api/seasons. Returns only CropMaster records mapped to that season, sorted by crop name then crop ID. Valid seasons with no mappings return an empty list and count=0. Missing, malformed, repeated or unknown season_id returns 422. Workbook mappings are preserved, including source ID/name inconsistencies: crop_id alone is not globally unique. Treat (season_id, crop_id) as the selection key; do not deduplicate by name. This endpoint does not change planner eligibility rules.","operationId":"listCropsBySeason","parameters":[{"description":"Season ID returned by GET /api/seasons.","example":1,"in":"query","name":"season_id","required":true,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropList"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List crops for a selected season","tags":["Reference data"]}},"/api/data":{"get":{"description":"Returns the in-memory JSON dataset. No upload or input-update API exists; source JSON is loaded at startup.","operationId":"getPlannerData","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerData"}}},"description":"Successful response"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Read current planning input","tags":["Reference data"]}},"/api/geocode/refresh":{"post":{"description":"Body is ignored. Updates accepted candidates in memory; resets plan/completions if coordinates change. Village acceptance requires name and PIN matches and no partial match. Review road access manually. Updates are sequential: a mid-request failure can leave partial coordinate changes.","operationId":"refreshGeocodes","requestBody":{"content":{"application/json":{"examples":{"Refresh":{"value":{}}},"schema":{"$ref":"#/components/schemas/EmptyRequest"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeReport"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Refresh coordinate candidates with Google","tags":["Locations"]}},"/api/locations/override":{"post":{"description":"Updates one location in memory and resets the plan/completions. Coordinates must fit the documented bounding box; this is not a precise India-boundary test. Restart restores source JSON values.","operationId":"overrideLocation","requestBody":{"content":{"application/json":{"examples":{"Illustrative current coordinate":{"value":{"id":"V1","lat":23.19305,"lon":79.83167}}},"schema":{"$ref":"#/components/schemas/CoordinateOverride"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverrideResult"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Override HQ or village coordinates","tags":["Locations"]}},"/api/master-data/activities":{"get":{"description":"Prepared ActivityMaster: 12 records with the updated durations, including Demo=45 and Field Day=240 minutes. /api/activity-master remains the original demo catalogue. Read-only: no solver, Maps request or active-plan changes.","operationId":"listPreparedActivities","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterActivityList"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"Read updated activity durations","tags":["Prepared masters"]}},"/api/master-data/activity-batches/{batch_id}":{"get":{"description":"Generation-time status and per-MDO URLs. Step 4 must revalidate current masters, coordinate expiry and actual roads. Batch files contain no stored Google coordinates or private source paths.","operationId":"getActivityBatch","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"pattern":"^[0-9a-f]{64}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityBatch"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM, batch or MDO scope"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid selection/options or generation limit exceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required data/storage unavailable"}},"summary":"Read an activity-batch summary","tags":["Activity generation"]}},"/api/master-data/activity-batches/{batch_id}/compare":{"post":{"description":"Target batches use exact allocated totals and current settings. Normal work is 8 hours, with up to 10 hours allowed including travel and HQ return; overtime is the first optimization priority. Daily village/total activity caps are unlimited unless configured. Daily activity-type bounds, spacing, linked harvest tasks and 200 km road cap (default) are checked. Traffic uses the selected representative-average profile; solver status reports whether optimality is proven. Returns 202; poll the job endpoint for independent per-MDO results. Comparison shares one matrix and never replaces the active plan.","operationId":"startRoadComparison","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"pattern":"^[0-9a-f]{64}$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadComparisonOptions"}}},"required":false},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadPlanningJob"}}},"description":"Job accepted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Compare both engines for a generated batch","tags":["Road planning"]}},"/api/master-data/activity-batches/{batch_id}/mdos/{geography_id}/activities":{"get":{"description":"Returns only this batch/MDO scope. Each record has targets 100/100/100, master duration, selected crop and permitted dates. No assigned_date is set. Available dates exclude weekly offs and the active calendar\u2019s holidays; synthetic_holidays labels sample dates.","operationId":"listGeneratedActivities","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"pattern":"^[0-9a-f]{64}$","type":"string"}},{"example":"10612","in":"path","name":"geography_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedActivityPage"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM, batch or MDO scope"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid selection/options or generation limit exceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required data/storage unavailable"}},"summary":"Read paginated independent activity records for an MDO","tags":["Activity generation"]}},"/api/master-data/activity-batches/{batch_id}/plan":{"post":{"description":"Target batches use exact allocated totals and current settings. Normal work is 8 hours, with up to 10 hours allowed including travel and HQ return; overtime is the first optimization priority. Daily village/total activity caps are unlimited unless configured. Daily activity-type bounds, spacing, linked harvest tasks and 200 km road cap (default) are checked. Traffic uses the selected representative-average profile; solver status reports whether optimality is proven. Returns 202; poll the job endpoint for independent per-MDO results. Omit geography_ids to include every allocated MDO. Blocked allocations prevent a claim of complete TBM coverage.","operationId":"startRoadPlanning","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"pattern":"^[0-9a-f]{64}$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadPlanningOptions"}}},"required":false},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadPlanningJob"}}},"description":"Job accepted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Start a TBM road-planning job","tags":["Road planning"]}},"/api/master-data/constraints":{"get":{"description":"Global and activity_types are separate sections. Null maximum means no configured cap. Workbook placeholder occurrence/village/activity maxima of 100 were imported as null; farmer bounds remain real bounds. VLM/IFC use explicit temporary IDs and each must occur exactly once on every MDO working day. They are independent village activities, with no Harvest Day linkage or 15-day spacing.","operationId":"getPlanningConstraints","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningConstraints"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target totals, month, allocation or constraints"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required settings unavailable"}},"summary":"Read global and activity-type settings","tags":["TBM targets and settings"]},"put":{"description":"Patch global and/or existing activity_type rules. expected_revision prevents lost edits. A change invalidates old target batches/plans; regenerate from the saved target totals. Normal 480 and maximum 600 minutes include service, driving and HQ return. Both engines minimize overtime before travel/date preference. No fixed travel/service split.","operationId":"updatePlanningConstraints","requestBody":{"content":{"application/json":{"example":{"activity_types":[{"activity_id":"79","duration_min":45,"max_per_day":null}],"expected_revision":1,"global":{"max_travel_km_per_day":200}},"schema":{"$ref":"#/components/schemas/PlanningConstraintsPatch"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningConstraints"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target totals, month, allocation or constraints"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required settings unavailable"}},"summary":"Save constraint settings with revision protection","tags":["TBM targets and settings"]}},"/api/master-data/generate-activities":{"post":{"description":"Send target_plan_id. Generates one record per allocated occurrence, with activity_target=1; farmer/acre shares sum exactly to entered period totals. Villages have equal selection weight. Missing inputs remain blocked allocations. Current mode does not use fixed targets of 100, a 20-village cap or a five-hour activity budget. All dates use the MDO state\u2019s supplied calendar. No Google road solve occurs in this preparation call.","operationId":"generateActivityBatch","requestBody":{"content":{"application/json":{"example":{"target_plan_id":"COPY_FROM_SAVE_TARGET_RESPONSE"},"schema":{"$ref":"#/components/schemas/GenerateTargetActivitiesRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityBatch"}}},"description":"Successful response"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityBatch"}}},"description":"New immutable batch created"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM, batch or MDO scope"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid selection/options or generation limit exceeded"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required data/storage unavailable"}},"summary":"Generate exact records from a saved TBM target plan","tags":["Activity generation"]}},"/api/master-data/holiday-calendars":{"get":{"description":"Empty calendars means approved input is still needed; it never means there are no public holidays. Read-only: no solver, Maps request or active-plan changes.","operationId":"listHolidayCalendars","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterHolidayCatalog"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"List available state/year calendar metadata","tags":["Prepared masters"]}},"/api/master-data/holidays":{"get":{"description":"Uses approved full-year calendars, or labelled synthetic calendars only when the registry explicitly enables demo mode. Missing/draft/incomplete calendars return 422; corrupt/duplicate calendars return 503. Read-only: no solver, Maps request or active-plan changes.","operationId":"getStateHolidays","parameters":[{"example":"IN-MH","in":"query","name":"state_code","required":true,"schema":{"pattern":"^IN-[A-Z]{2}$","type":"string"}},{"example":2026,"in":"query","name":"year","required":true,"schema":{"maximum":2100,"minimum":2000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterHolidayCalendar"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"Read one approved state/year holiday calendar","tags":["Prepared masters"]}},"/api/master-data/monthly-plans":{"post":{"description":"Collects ALL active monthly crop targets for this TBM/month. Each occurrence keeps its source target, crop, farmer/acre share and date window. Overlaps share one MDO daily capacity. A shared CP-SAT allocation stage balances counts within date/frequency/service bounds; both routing engines receive that same workload. Necessary allocation failure returns 422 before Google calls. Otherwise returns 202/job_id. Poll the usual job endpoint. MDO results are staged until EVERY assigned MDO validates and every target/activity total reconciles. Failure or a concurrent target edit means no new monthly plan is published. No activities are dropped and no MDO subset can be published. A failed attempt does not replace an older plan. Daily VLM/IFC apply once across overlaps and must cover EVERY working day of the full month. Saved target windows/counts must cover those dates, including dates outside other crop ranges. Unfinished/heuristic search failure is not proof of infeasibility.","operationId":"generateCombinedMonthlyPlan","requestBody":{"content":{"application/json":{"example":{"algorithm":"ortools","daily_requirement_scope":"full_month","month":"2026-12","seconds":20,"tbm_id":"local:gaurav-baliyan"},"schema":{"$ref":"#/components/schemas/MonthlyPlanRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadPlanningJob"}}},"description":"Job accepted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target set, missing MDO input or allocation infeasibility"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Queue full"}},"summary":"Generate one month from all saved active targets","tags":["Combined monthly planning"]}},"/api/master-data/planning-inputs":{"post":{"description":"Returns all nonvacant MDO contexts, selected season/crop mappings, updated activities/defaults and state calendars. An invalid selection returns 422. A valid selection with incomplete source data returns 200 with ready=false and per-MDO issues. Explicitly configured PoC mode permits fresh centres and sample holidays while marking production_ready=false; candidates are never promoted to verified. Village lists are paginated through villages_url. No village/activity combination, activity targets or route plan is generated here. Read-only: no solver, Maps request or active-plan changes.","operationId":"prepareMasterPlanningInputs","requestBody":{"content":{"application/json":{"example":{"crop_ids":[1,28],"end_date":"2026-12-31","season_id":1,"start_date":"2026-12-01","tbm_id":"local:gaurav-baliyan"},"schema":{"$ref":"#/components/schemas/MasterPlanningSelection"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterPlanningInputs"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"Validate TBM, season, crops and dates","tags":["Prepared masters"]}},"/api/master-data/planning-jobs/{job_id}":{"get":{"description":"Includes planned/compared/blocked/failed counts, controlled per-MDO errors and available metrics. completed describes job execution; comparison results may still contain per-engine failures.","operationId":"getRoadPlanningJob","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"pattern":"^[0-9a-f]{32}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadPlanningJob"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Read background planning progress","tags":["Road planning"]}},"/api/master-data/planning-jobs/{job_id}/mdos/{geography_id}/geometry":{"post":{"description":"Explicit billable Google route request for this MDO/date/sequence. It does not reschedule activities or persist geometry. The geometry API forecast duration may differ from the validated representative-average schedule.","operationId":"getRoadMDOGeometry","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"pattern":"^[0-9a-f]{32}$","type":"string"}},{"in":"path","name":"geography_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadGeometryRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadGeometryResponse"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Fetch a selected day\u2019s Google road polyline","tags":["Road planning"]}},"/api/master-data/planning-jobs/{job_id}/mdos/{geography_id}/plan":{"get":{"description":"Revalidates current input fingerprint and coordinate expiry. Days include route points, stops, independent activities and arrival/return times. Geometry is fetched explicitly for a selected day; no Google call is made by this read.","operationId":"getRoadMDOPlan","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"pattern":"^[0-9a-f]{32}$","type":"string"}},{"in":"path","name":"geography_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadMDOPlan"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Read one MDO plan and revision","tags":["Road planning"]}},"/api/master-data/planning-jobs/{job_id}/mdos/{geography_id}/reroute":{"post":{"description":"Use revision from GET plan. Prior dates are locked; confirmed completed records are removed from remaining work. New confirmations must be eligible today and fit elapsed service time. Earlier completions are retained. Today may have no pending activity; the current-position-to-HQ return must still fit remaining time. All other outstanding records must remain scheduled. Failure preserves the original plan and revision; successful independent validation atomically publishes revision +1. Revision mismatch returns 409. For target batches with a daily distance cap, travelled_km_today is required so already-driven kilometres count against the full-day limit. Normal hours remain preferred; configured extended hours are the hard limit.","operationId":"rerouteRoadMDOPlan","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"pattern":"^[0-9a-f]{32}$","type":"string"}},{"in":"path","name":"geography_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadRerouteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoadMDOPlan"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown batch, job or MDO"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Plan not ready, stale inputs or revision conflict"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid inputs, blocked masters or planning/road failure"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Planning queue is full"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required master data/storage unavailable"}},"summary":"Reroute remaining records for one MDO","tags":["Road planning"]}},"/api/master-data/settings":{"get":{"description":"Returns 100/100/100 per-record demo targets, Monday-Saturday workweek and maximum-six activity cap. Read-only: no solver, Maps request or active-plan changes.","operationId":"getPreparedSettings","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterSettings"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"Read planning defaults and workweek","tags":["Prepared masters"]}},"/api/master-data/target-plans":{"get":{"description":"Target summaries for the My Targets screen. Company authorization must be supplied by the host application.","operationId":"listTBMTargetPlans","parameters":[{"in":"query","name":"tbm_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":500,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}},{"description":"Return active monthly targets for this month; omit to inspect legacy/history entries too.","in":"query","name":"month","schema":{"example":"2026-12","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlanList"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target totals, month, allocation or constraints"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required settings unavailable"}},"summary":"List saved target plans for a TBM","tags":["TBM targets and settings"]},"post":{"description":"Save one crop/date-window component of a monthly plan. Daily minima are enforced across the combined month, not independently for each overlapping crop. Activity/farmer/acre values remain exact per-target totals. Allocations in this response are previews; monthly allocation balances all targets jointly. Use POST /monthly-plans to solve all active saved targets. Existing legacy single-target objects can be promoted by editing/saving once through PUT.","operationId":"createTBMTargetPlan","requestBody":{"content":{"application/json":{"example":{"activity_targets":[{"acre_target":1200,"activity_id":"79","activity_target":50,"farmer_target":300},{"acre_target":4880,"activity_id":"VLM","activity_target":122,"farmer_target":1220},{"acre_target":4880,"activity_id":"IFC","activity_target":122,"farmer_target":1220}],"crop_id":1,"end_date":"2026-12-31","season_id":1,"start_date":"2026-12-01","tbm_id":"local:gaurav-baliyan"},"schema":{"$ref":"#/components/schemas/TargetPlanRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlan"}}},"description":"Successful response"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlan"}}},"description":"New immutable target plan created"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target totals, month, allocation or constraints"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required settings unavailable"}},"summary":"Save the TBM\u2019s monthly activity totals","tags":["TBM targets and settings"]}},"/api/master-data/target-plans/{target_plan_id}":{"delete":{"description":"Logical removal with expected_revision; no files/history are deleted. Save an edit to reactivate it. Affected monthly plans become stale.","operationId":"archiveMonthlyCropTarget","parameters":[{"in":"path","name":"target_plan_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveTargetRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlan"}}},"description":"Saved"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target set, missing MDO input or allocation infeasibility"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Queue full"}},"summary":"Archive a saved crop target","tags":["Combined monthly planning"]},"get":{"description":"Includes entered totals and allocations; this response is not a road-optimized plan.","operationId":"getTBMTargetPlan","parameters":[{"in":"path","name":"target_plan_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlan"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target totals, month, allocation or constraints"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Required settings unavailable"}},"summary":"Read targets and MDO allocations","tags":["TBM targets and settings"]},"put":{"description":"Send expected_revision and all target fields. Keeps the ID and increments revision. Crop/date window/totals may change, but TBM cannot change. Earlier revisions are retained. Affected monthly plans become stale. Save validates inputs; the combined month checks shared road/time capacity.","operationId":"editMonthlyCropTarget","parameters":[{"in":"path","name":"target_plan_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlanEditRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetPlan"}}},"description":"Saved"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown target/TBM"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Revision conflict or stale inputs"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid target set, missing MDO input or allocation infeasibility"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Queue full"}},"summary":"Edit and save a crop target","tags":["Combined monthly planning"]}},"/api/master-data/tbms":{"get":{"description":"Uses the Step-1 manifest. Local TBM IDs are provisional identifiers; vacant MDOs and their villages are excluded. Read-only: no solver, Maps request or active-plan changes.","operationId":"listMasterTBMs","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"maximum":1000000000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterTBMList"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"List TBMs and nonvacant planning counts","tags":["Prepared masters"]}},"/api/master-data/tbms/{tbm_id}/mdos":{"get":{"description":"Returns geography IDs, names, HQ and state metadata. Missing/expired/invalid coordinates are null. Fresh candidate centres remain marked unverified. Unmapped assignments remain visible for review. Read-only: no solver, Maps request or active-plan changes.","operationId":"listMasterMDOs","parameters":[{"example":"local:gaurav-baliyan","in":"path","name":"tbm_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"maximum":1000000000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterMDOList"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"List nonvacant MDOs under a TBM","tags":["Prepared masters"]}},"/api/master-data/tbms/{tbm_id}/mdos/{geography_id}/villages":{"get":{"description":"TBM and geography scope are required. IDs/PINs remain strings. Search matches name, code or PIN; sort is name then village code. Expired Google coordinates are masked even in a running process. total is the filtered count before paging. This ID scope is not an authentication layer. Read-only: no solver, Maps request or active-plan changes.","operationId":"listMasterVillages","parameters":[{"example":"local:gaurav-baliyan","in":"path","name":"tbm_id","required":true,"schema":{"type":"string"}},{"example":"10612","in":"path","name":"geography_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"maximum":1000000000,"minimum":0,"type":"integer"}},{"in":"query","name":"search","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterVillageList"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"List villages mapped to one MDO","tags":["Prepared masters"]}},"/api/master-data/working-days":{"get":{"description":"Excludes Sundays and the active calendar\u2019s holidays. Saturday is working; Sunday holidays are excluded once. Synthetic calendars are labelled calendar_mode=demo and synthetic_holidays=true. Every state/year needs a valid calendar; arbitrary ranges and cross-year dates are supported within 2000-2100. No fixed 7/10/20/31-day horizon. Read-only: no solver, Maps request or active-plan changes.","operationId":"getWorkingDays","parameters":[{"example":"IN-MH","in":"query","name":"state_code","required":true,"schema":{"pattern":"^IN-[A-Z]{2}$","type":"string"}},{"example":"2026-12-01","in":"query","name":"start_date","required":true,"schema":{"format":"date","type":"string"}},{"example":"2026-12-31","in":"query","name":"end_date","required":true,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterWorkingDays"}}},"description":"Success; planning-input readiness may still be false."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Unknown TBM or MDO outside this TBM/nonvacant planning pool."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Invalid input or missing approved holiday calendar."},"500":{"$ref":"#/components/responses/ServerError"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterError"}}},"description":"Prepared data is missing or invalid."}},"summary":"Calculate working dates in an inclusive range","tags":["Prepared masters"]}},"/api/plan":{"post":{"description":"Runs the chosen engine against server-side input, validates output and requests Google road geometry. On success replaces the active plan and clears completion tracking. Earlier state survives planning failure. The request does not accept custom tasks, planning dates, limits or a solve-time setting. TBM/season/crop/date selection fields are rejected; Step 2 uses /api/master-data/planning-inputs. Geometry failure may appear as route_geometry_error inside an otherwise successful 200 response.","operationId":"generatePlan","requestBody":{"content":{"application/json":{"examples":{"ALNS":{"value":{"algorithm":"alns"}},"OR-Tools":{"value":{"algorithm":"ortools"}}},"schema":{"$ref":"#/components/schemas/PlanRequest"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Generate an original one-MDO demo plan","tags":["Planning"]}},"/api/plans/generate":{"post":{"description":"Uses ALL active saved targets for this TBL/month and EVERY assigned nonvacant MDO. The client supplies no crop/activity/village subset. Model A uses OR-Tools routing; Model B uses ALNS routing; existing shared monthly allocation, constraints, MDO-state calendars, exact targets and all-or-nothing publication remain intact. The month is validated and shared allocation runs during request preparation; then a background routing job is started. Show indeterminate loading while waiting for this response, then poll data.status_url. Returns HTTP 202 with job_id and status/message/data. This is acceptance, not a guarantee of a generated plan. Default road times use sampled_average traffic. Saving targets or loading model choices does not run this operation. Necessary allocation infeasibility returns 422 before road calls; road/search failures appear in job polling. Show the success screen only when data.plan_generated is true. Daily VLM/IFC cover the full working month, once across all crop targets. No Overall Plan view/export response is added by this operation.","operationId":"generateScreenMonthlyPlan","requestBody":{"content":{"application/json":{"example":{"model_id":"model_a","month":"2026-12","tbl_id":"local:gaurav-baliyan"},"schema":{"$ref":"#/components/schemas/ScreenGeneratePlanRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenGenerationResponse"}}},"description":"Accepted planning request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/job or job outside the requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Inputs changed during generation"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid request, no saved targets, incomplete inputs or infeasible allocation"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Planning queue full; retry later"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Master data unavailable"}},"summary":"Generate a plan on explicit button click","tags":["Generate Plan screen"]}},"/api/plans/jobs/{job_id}":{"get":{"description":"Read the existing monthly planning job without rerunning either engine. Uses the same source-target and constraint freshness checks as the canonical job endpoint. A changed target/settings marks a published job stale and clears plan_generated. Loading: terminal=false. Success: plan_generated=true. Other terminal states: stop polling and show error plus per-MDO errors. Envelope status=true means the status was fetched successfully, even when data.state=failed. Progress is an MDO-count fraction, not a time estimate or feasibility score. A restarted worker reports interrupted and requires an explicit new Generate click.","operationId":"getScreenGenerationStatus","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"description":"Copy from the Generate Plan response.","pattern":"^[0-9a-f]{32}$","type":"string"}},{"in":"query","name":"tbl_id","required":true,"schema":{"description":"Existing tbm_id, named tbl_id by the frontend.","example":"local:gaurav-baliyan","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenGenerationResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/job or job outside the requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Inputs changed during generation"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid request, no saved targets, incomplete inputs or infeasible allocation"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Planning queue full; retry later"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Master data unavailable"}},"summary":"Poll generation progress and outcome","tags":["Generate Plan screen"]}},"/api/plans/models":{"get":{"description":"Returns Empower Model A (model_a, ortools) and Empower Model B (model_b, alns). Read-only metadata. Does not start allocation, road calls or route optimization.","operationId":"getScreenPlanningModels","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenPlanningModelsResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/job or job outside the requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Inputs changed during generation"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid request, no saved targets, incomplete inputs or infeasible allocation"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Planning queue full; retry later"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Master data unavailable"}},"summary":"Load Select Model options","tags":["Generate Plan screen"]}},"/api/reroute":{"post":{"description":"Generate a plan first. Date must be in that plan. Preserves earlier days and excludes completed/frozen tasks; unverified earlier tasks are not automatically carried forward. Explicit completion IDs accumulate. Completed-today work counts toward daily caps. Omitted algorithm uses the active plan engine; omitted current_time defaults to 12:00. Remaining work must respect availability and return to HQ. A failed reroute leaves the active state unchanged.","operationId":"reroutePlan","requestBody":{"content":{"application/json":{"examples":{"No completion claimed":{"value":{"algorithm":"alns","completed_task_ids":[],"current_time":"12:00","date":"2026-11-23","lat":23.19305,"lon":79.83167}}},"schema":{"$ref":"#/components/schemas/RerouteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}},"description":"Successful response"},"422":{"$ref":"#/components/responses/PlanningError"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Replan from a location and time","tags":["Planning"]}},"/api/seasons":{"get":{"description":"Returns SeasonMaster records in season-ID order. Pass the selected season_id to GET /api/crops. Read-only master data; independent of the current plan and sample task labels.","operationId":"listSeasons","responses":{"200":{"content":{"application/json":{"example":{"count":3,"seasons":[{"season_id":1,"season_name":"Kharif"},{"season_id":2,"season_name":"Rabi"},{"season_id":3,"season_name":"Summer"}]},"schema":{"$ref":"#/components/schemas/SeasonList"}}},"description":"Successful response"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"List seasons for selection","tags":["Reference data"]}},"/api/targets":{"get":{"description":"Returns status/message/data, where data is one summary row per active saved crop/date-window target. Totals are sums of that target\u2019s activity rows. Archived targets are excluded; no matches gives an empty array. Search matches season/crop names, case-insensitively. Optional filters affect the grid only, not summary cards.","operationId":"listScreenTargets","parameters":[{"in":"query","name":"tbl_id","required":true,"schema":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"}},{"in":"query","name":"month","required":true,"schema":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"}},{"in":"query","name":"search","required":false,"schema":{"type":"string"}},{"in":"query","name":"season_id","required":false,"schema":{"minimum":0,"type":"integer"}},{"in":"query","name":"crop_id","required":false,"schema":{"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetListResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"List My Targets grid rows for a month","tags":["My Targets screens"]},"post":{"description":"One season, one crop and an inclusive date range within one calendar month. Enter period totals per activity across this TBL, not per MDO. Server validates master IDs, quantities and farmer bounds; it sums the three grid totals from activity rows. Omit unused activities or send all three values as zero. At least one occurrence is required. Names come from masters. Returns 201 when a new target is created or 200 when a matching, unmodified saved record is reused. Use PUT with the saved ID to edit an existing target. Response includes activity rows for the edit form. No optimizer or Google call runs on Save. All targets are saved in the same store used by combined monthly generation.","operationId":"saveScreenTarget","requestBody":{"content":{"application/json":{"example":{"activities":[{"acreage_target":20,"activities_target":10,"activity_id":"79","farmers_target":10}],"crop_id":28,"from_date":"2026-12-01","season_id":1,"tbl_id":"local:gaurav-baliyan","to_date":"2026-12-18"},"schema":{"$ref":"#/components/schemas/ScreenTargetInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetDetailResponse"}}},"description":"Success"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetDetailResponse"}}},"description":"New target saved"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"Save Setup My Target form","tags":["My Targets screens"]}},"/api/targets/summary":{"get":{"description":"Totals over all active saved targets for this TBL/month. total_mdos counts assigned nonvacant MDOs, including MDOs whose coordinates still need preparation. The other three cards use activities_target, farmers_target and acreage_target. With no targets they are zero. Grid search/filter settings do not affect these totals.","operationId":"getScreenTargetSummary","parameters":[{"in":"query","name":"tbl_id","required":true,"schema":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"}},{"in":"query","name":"month","required":true,"schema":{"example":"2026-12","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetCardsResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"Read My Target dashboard cards","tags":["My Targets screens"]}},"/api/targets/{target_id}":{"delete":{"description":"Send tbl_id in the query and expected_revision in the JSON body. Archives the saved target, removing it from the active month list/cards and future monthly generation. History is retained. Existing monthly plans referencing this target become stale. Archived targets return 404 through these screen endpoints.","operationId":"deleteScreenTarget","parameters":[{"in":"path","name":"target_id","required":true,"schema":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"}},{"in":"query","name":"tbl_id","required":true,"schema":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"expected_revision":1},"schema":{"$ref":"#/components/schemas/ArchiveTargetRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetDeleteResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"Delete a target from My Targets","tags":["My Targets screens"]},"get":{"description":"Returns header values, calculated totals, revision and all current activity types with saved quantities. Unspecified activity types have zero quantities. Copy revision into expected_revision on Update/Delete. Names/durations are display fields: send only activity_id and the three target quantities when saving.","operationId":"getScreenTarget","parameters":[{"in":"path","name":"target_id","required":true,"schema":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"}},{"in":"query","name":"tbl_id","required":true,"schema":{"description":"Frontend alias for the existing tbm_id. Use a real ID from /api/master-data/tbms.","example":"local:gaurav-baliyan","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetDetailResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"Load a saved target into Edit form","tags":["My Targets screens"]},"put":{"description":"Send the complete form and expected_revision from the latest GET. Crop, dates and per-activity quantities can change; TBL cannot change. Keeps target_id, increments revision and retains previous values in history. A stale revision returns 409. Existing monthly plans referencing changed targets become stale.","operationId":"updateScreenTarget","parameters":[{"in":"path","name":"target_id","required":true,"schema":{"description":"Saved target ID, identical to target_plan_id in the canonical monthly API.","pattern":"^[0-9a-f]{64}$","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"activities":[{"acreage_target":20,"activities_target":10,"activity_id":"79","farmers_target":10}],"crop_id":28,"expected_revision":1,"from_date":"2026-12-01","season_id":1,"tbl_id":"local:gaurav-baliyan","to_date":"2026-12-18"},"schema":{"$ref":"#/components/schemas/ScreenTargetEditInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetDetailResponse"}}},"description":"Success"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Unknown TBL/target or target outside requested TBL scope"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Revision changed; reload before saving or deleting"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Invalid inputs"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenTargetError"}}},"description":"Required master data unavailable"}},"summary":"Save edited target details","tags":["My Targets screens"]}}},"servers":[{"description":"Current Flask server","url":"/"}],"tags":[{"description":"Frontend Save/List/Edit/Delete contracts using status/message/data. Shares the existing monthly target store. Use /api/seasons, /api/crops?season_id=..., and /api/master-data/activities for form lookups.","name":"My Targets screens"},{"description":"Choose a month and model, explicitly start monthly planning, then poll for loading/success/failure. Model A = OR-Tools; Model B = ALNS. Overall-plan views/export are separate.","name":"Generate Plan screen"},{"name":"Reference data"},{"name":"Planning"},{"name":"Locations"},{"description":"Step 2: TBM masters, selections and working calendars; no optimization or Google calls.","name":"Prepared masters"},{"description":"Step 3: generate and persist per-MDO records; route optimization follows in Step 4.","name":"Activity generation"},{"description":"Step 4: independent per-MDO plans, background jobs, fair comparison and revision-protected reroutes.","name":"Road planning"},{"description":"Exact monthly TBM activity totals and separately editable global/activity-type constraints.","name":"TBM targets and settings"},{"description":"Save several crop/date windows, then solve one shared month. Publish only when all targets and MDOs pass.","name":"Combined monthly planning"}]}
