update docs

sharedDocs/BACKEND_API_REFERENCE.md

@@ -619,6 +619,7 @@ role — the response body carries no distinction between "not found" and "forbi
   "startPoint": "string",
   "endPoint": "string",
   "length": 12.5,
+  "ownerUserId": "guid | null",
   "isActive": true,
   "createdAt": "datetime"
 }
@@ -632,6 +633,81 @@ role — the response body carries no distinction between "not found" and "forbi
 Returns the same `RouteResponse` shape as above. `404` if the route or the target region doesn't
 exist (or either is inactive).
 
+#### Route & Sales Visit Management
+
+Bulk store assignment, owner assignment, and GPS check-in/out for a SalesRep's daily visit
+schedule. Not gated by the `routes.*` permission codes above — access is checked in
+`RouteService` via `IScopeAccessService.HasRouteScopeAsync`, with a `RouteManagerRoleLevel` (20,
+i.e. Supervisor and above) floor for the assignment endpoints. All endpoints below return `404`
+if the route doesn't exist, is inactive, or the caller lacks route scope — the response body
+carries no distinction between "not found" and "forbidden".
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/api/routes/{id}/stores` | Bulk-assign a set of stores to this route (replaces each store's `routeId`) |
+| `PUT` | `/api/routes/{id}/owner` | Assign or reassign the route's owning SalesRep (`OwnerUserId`) |
+| `POST` | `/api/routes/{id}/optimize` | Route sequence optimization — **not yet implemented**, always returns `501 Not Implemented` |
+| `POST` | `/api/routes/{id}/visits/check-in` | Record a GPS check-in at a store on this route |
+| `POST` | `/api/routes/{id}/visits/check-out` | Record check-out for an open visit at a store on this route |
+
+**Assign stores request / response:**
+```json
+// POST /api/routes/{id}/stores
+{ "storeIds": ["guid", "guid", "..."] }
+```
+Returns the `RouteResponse` shape. All IDs must reference existing stores or the request is
+rejected with `404` (no partial assignment).
+```json
+{ "id": "guid", "regionId": "guid", "routeName": "string", "startPoint": "string", "endPoint": "string", "length": 12.5, "ownerUserId": "guid | null", "isActive": true, "createdAt": "datetime" }
+```
+
+**Assign owner request / response:**
+```json
+// PUT /api/routes/{id}/owner
+{ "salesRepId": "guid" }   // must be an active User
+```
+Returns the same `RouteResponse` shape. `404` if the target user doesn't exist or is inactive.
+
+**Check-in request / response:**
+```json
+// POST /api/routes/{id}/visits/check-in
+{
+  "storeId": "guid",         // must currently be assigned to this route
+  "latitude": 6.927079,
+  "longitude": 79.861244,
+  "timestamp": "datetime | null"   // optional, defaults to server time
+}
+```
+```json
+{
+  "id": "guid",
+  "routeId": "guid",
+  "storeId": "guid",
+  "userId": "guid",              // caller's user ID — the visiting rep
+  "checkInAt": "datetime",
+  "isDeviationFlagged": false,   // true if GPS is > 500m (Haversine) from the store's registered lat/long
+  "checkOutAt": "datetime | null"
+}
+```
+`isDeviationFlagged` is a basic distance check only — it does not yet trigger any alert/notification
+(see [docs/09_fraud_controls.md] `sendRouteDeviationAlert`, which is not implemented).
+
+**Check-out request / response:**
+```json
+// POST /api/routes/{id}/visits/check-out
+{
+  "storeId": "guid",
+  "timestamp": "datetime | null"   // optional, defaults to server time
+}
+```
+Returns the same shape as check-in with `checkOutAt` populated. `404` if there's no open
+(checked-in, not yet checked-out) visit for that route+store.
+
+There is no endpoint to list a route's open/in-progress visits — check-out requires the caller to
+already know which store they checked into. A store's full visit history is available via
+`GET /api/stores/{id}/visit-history` (see [§6.9 Stores](#69-stores)), which reads from this same
+visit log.
+
 ---
 
 ### 6.7 Vehicles