ncaron
/
matcher
mirror of https://gitlab.com/mobicoop/v3/service/matcher.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

udpate readme

This commit is contained in:
sbriat 2023-09-28 16:31:26 +02:00
parent b810bc86e6
commit 2b59e99121
1 changed files with 229 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

229
README.md
View File

@ -9,3 +9,232 @@ You need [Docker](https://docs.docker.com/engine/) and its [compose](https://doc
You also need NodeJS installed locally : we **strongly** advise to install [Node Version Manager](https://github.com/nvm-sh/nvm) and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).
The API will run inside a docker container, **but** the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint or Prettier with fix-on-save).
A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.
# Installation
- copy `.env.dist` to `.env` :
```bash
cp .env.dist .env
```
Modify it if needed.
- install the dependencies :
```bash
npm install
```
- start the containers :
```bash
docker compose up -d
```
The app runs automatically on port **5005**.
## Database migration
Before using the app, you need to launch the database migration (it will be launched inside the container) :
```bash
npm run migrate
```
## Usage
The app exposes the following [gRPC](https://grpc.io/) services :
- **Match** : find matching ads corresponding to the given criteria
For example, as a passenger, to search for drivers for a punctual carpool :
```json
{
"driver": false,
"passenger": true,
"frequency": "PUNCTUAL",
"algorithmType": "PASSENGER_ORIENTED",
"fromDate": "2024-06-05",
"toDate": "2024-06-05",
"schedule": [
{
"time": "07:30"
}
],
"waypoints": [
{
"houseNumber": "23",
"street": "rue de viller",
"postalCode": "54300",
"locality": "Lunéville",
"lon": 6.490527,
"lat": 48.590119,
"country": "France",
"position": 0
},
{
"houseNumber": "3",
"street": "rue du passage",
"postalCode": "67117",
"locality": "Ittenheim",
"lon": 7.594361,
"lat": 48.603004,
"country": "France",
"position": 1
}
]
}
```
As a passenger, to search for drivers for a recurrent carpool :
```json
{
"driver": false,
"passenger": true,
"frequency": "RECURRENT",
"algorithmType": "PASSENGER_ORIENTED",
"fromDate": "2024-01-02",
"toDate": "2024-06-30",
"strict": true,
"page": 1,
"perPage": 5,
"schedule": [
{
"day": 1,
"time": "07:30"
},
{
"day": 2,
"time": "07:45"
},
{
"day": 4,
"time": "07:30"
},
,
{
"day": 5,
"time": "07:30"
}
],
"waypoints": [
{
"houseNumber": "298",
"street": "Aveue de la liberté",
"postalCode": "86180",
"locality": "Buxerolles",
"lon": 0.364394,
"lat": 46.607501,
"country": "France",
"position": 0
},
{
"houseNumber": "1",
"street": "place du 8 mai 1945",
"postalCode": "47310",
"locality": "Roquefort",
"lon": 0.559606,
"lat": 44.175994,
"country": "France",
"position": 1
}
]
}
```
The list of possible criteria :
- **id** (optional): the id of a previous matching result (as a uuid)
- **driver** (boolean, optional): to search for passengers (_default : false_)
- **passenger** (boolean, optional): to search fo drivers (_default : true_)
- **frequency**: the frequency of the search (`PUNCTUAL` or `RECURRENT`)
- **strict** (boolean, optional): if set to true, allow matching only with similar frequency ads (_default : false_)
- **fromDate**: start date for recurrent ad, carpool date for punctual ad
- **toDate**: end date for recurrent ad, same as fromDate for punctual ad
- **schedule**: an array of schedule items, a schedule item containing :
- the week day as a number, from 0 (sunday) to 6 (saturday) if the ad is recurrent (default to fromDate day for punctual search)
- the departure time (as HH:MM)
- the margin around the departure time in seconds (optional) (_default : 900_)
- **seatsProposed** (integer, optional): number of seats proposed as driver (_default : 3_)
- **seatsRequested** (integer, optional): number of seats requested as passenger (_default : 1_)
- **waypoints**: an array of addresses that represent the waypoints of the journey (only first and last waypoints are used for passenger ads). Note that positions are **required** and **must** be consecutives
- **algorithmType** (optional): the type of algorithm to use (as of 2023-09-28, only the default `PASSENGER_ORIENTED` is accepted)
- **remoteness** (integer, optional): an integer to indicate the maximum flying distance (in metres) between the driver route and the passenger pick-up / drop-off points (_default : 15000_)
- **useProportion** (boolean, optional): a boolean to indicate if the matching algorithm will compare the distance of the passenger route against the distance of the driver route (_default : 1_). Works in combination with **proportion** parameter
- **proportion** (float, optional): a fraction (float between 0 and 1) to indicate minimum proportion of the distance of the passenger route against the distance of the driver route (_default : 0.3_). Works in combination with **use_proportion** parameter
- **useAzimuth** (boolean, optional): a boolean to indicate if the matching algorithm will use the azimuth of the driver and passenger routes (_default : 1_)
- **azimuthMargin** (integer, optional): an integer (representing the number of degrees) to indicate the range around the opposite azimuth to consider the candidate route excluded (_default : 10_)
- **maxDetourDistanceRatio** (float, optional): a fraction (float between 0 and 1) of the driver route distance to indicate the maximum detour distance acceptable for a passenger (_default : 0.3_)
- **maxDetourDurationRatio** (float, optional): a fraction (float between 0 and 1) of the driver route duration to indicate the maximum detour duration acceptable for a passenger (_default : 0.3_)
- **page** (integer, optional): the page of results to display (_default : 1_)
- **perPage** (integer, optional): the number of results to display per page (_default : 10_)
If the matching is successful, you will get a result, containing :
- **id**: the id of the matching; as matching is a time-consuming process, results are cached and thus accessible later using this id (pagination works as well !)
- **total**: the total number of results
- **page**: the number of the page that is returned (may be different than the number of the required page, if number of results does not match with perPage parameter)
- **perPage**: the number of results per page (as it may not be specified in the request)
- **data**: an array of the results themselves, each including:
- **id**: an id for the result
- **adId**: the id of the ad that matches
- **role**: the role of the ad owner in that match
- **distance**: the distance in metres of the resulting carpool
- **duration**: the duration in seconds of the resulting carpool
- **initialDistance**: the initial distance in metres for the driver
- **initialDuration**: the initial duration in seconds for the driver
- **distanceDetour**: the detour distance in metres
- **durationDetour**: the detour duration in seconds
- **distanceDetourPercentage**: the detour distance in percentage of the original distance
- **durationDetourPercentage**: the detour duration in percentage of the original duration
- **journeys**: the possible journeys for the carpool (one journey for punctual carpools, one or more journeys for recurrent carpools), each including:
- **day**: the week day for the journey, as a number, from 0 (sunday) to 6 (saturday)
- **firstDate**: the first possible date for the journey
- **lastDate**: the last possible date for the journey
- **steps**: the steps of the journey (coordinates with distance, duration and actors implied), each including:
- **distance**: the distance to reach the step in metres
- **duration**: the duration to reach the step in seconds
- **lon**: the longitude of the point for the step
- **lat**: the longitude of the point for the step
- **time**: the driver time at that step
- **actors**: the actors for that step:
- **role**: the role of the actor (`DRIVER` or `PASSENGER`)
- **target**: the meaning of the step for the actor:
- _START_ for the first point of the actor
- _FINISH_ for the last point of the actor
- _INTERMEDIATE_ for a driver intermediate point
- _NEUTRAL_ for a passenger point from the point of view of a driver
## Tests / ESLint / Prettier
Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone).
The integration tests use a dedicated database (see _db-test_ section of _docker-compose.yml_).
```bash
# run all tests (unit + integration)
npm run test
# unit tests only
npm run test:unit
# integration tests only
npm run test:integration
# coverage
npm run test:cov
# ESLint
npm run lint
# Prettier
npm run pretty
```
## License
Mobicoop V3 - Matcher Service is [AGPL licensed](LICENSE).