ad/README.md

245 lines
6.7 KiB
Markdown
Raw Normal View History

2023-05-03 11:43:21 +00:00
# Mobicoop V3 - Ad
2023-05-03 11:35:58 +00:00
2023-05-03 11:43:21 +00:00
Ad service for Mobicoop V3.
2023-05-03 11:35:58 +00:00
2023-05-03 11:43:21 +00:00
## Requirements
2023-05-03 11:35:58 +00:00
2023-05-03 11:43:21 +00:00
You need [Docker](https://docs.docker.com/engine/) and its [compose](https://docs.docker.com/compose/) plugin.
2023-05-03 11:35:58 +00:00
2023-05-03 11:43:21 +00:00
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).
2023-05-03 11:35:58 +00:00
2023-05-03 11:43:21 +00:00
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).
2023-06-02 14:31:35 +00:00
2023-06-06 08:22:50 +00:00
A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.
2023-06-02 14:31:35 +00:00
## 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 **5006**.
## 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 :
2023-06-23 13:35:37 +00:00
- **FindById** : find an ad by its id
2023-06-02 14:31:35 +00:00
```json
{
2023-06-23 13:35:37 +00:00
"id": "80126a61-d128-4f96-afdb-92e33c75a3e1"
2023-06-02 14:31:35 +00:00
}
```
2023-07-26 15:05:16 +00:00
- **Create** : create an ad
2023-06-02 14:31:35 +00:00
Punctual driver ad :
2023-06-02 14:31:35 +00:00
```json
{
2023-06-23 13:35:37 +00:00
"userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
2023-06-02 14:31:35 +00:00
"driver": true,
2023-10-16 15:11:20 +00:00
"passenger": false,
2023-06-23 13:35:37 +00:00
"seatsProposed": 3,
2023-06-02 14:31:35 +00:00
"frequency": "PUNCTUAL",
2023-06-23 13:35:37 +00:00
"fromDate": "2023-01-15",
"toDate": "2023-01-15",
2023-07-26 15:05:16 +00:00
"schedule": [
{
2023-10-16 15:11:20 +00:00
"day": 0,
2023-07-26 15:05:16 +00:00
"time": "09:00",
"margin": 900
}
],
2023-06-23 13:35:37 +00:00
"waypoints": [
{
"position": 0,
2023-06-23 13:35:37 +00:00
"lon": 48.689445,
"lat": 6.17651,
"houseNumber": "5",
"street": "Avenue Foch",
"locality": "Nancy",
"postalCode": "54000",
"country": "France"
},
{
"position": 1,
"lon": 48.8566,
"lat": 2.3522,
"locality": "Paris",
"postalCode": "75000",
"country": "France"
}
]
}
```
2023-06-02 14:31:35 +00:00
Punctual driver and passenger ad :
```json
{
2023-06-23 13:35:37 +00:00
"userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
"driver": true,
2023-10-16 15:11:20 +00:00
"passenger": true,
2023-06-23 13:35:37 +00:00
"seatsProposed": 3,
"seatsRequested": 1,
"frequency": "PUNCTUAL",
2023-06-23 13:35:37 +00:00
"fromDate": "2023-01-15",
"toDate": "2023-01-15",
2023-07-26 15:05:16 +00:00
"schedule": [
{
2023-10-16 15:11:20 +00:00
"day": 0,
2023-07-26 15:05:16 +00:00
"time": "09:00",
"margin": 900
}
],
2023-06-23 13:35:37 +00:00
"waypoints": [
{
"position": 0,
2023-06-23 14:34:32 +00:00
"lon": 48.689445,
"lat": 6.17651,
"houseNumber": "5",
"street": "Avenue Foch",
"locality": "Nancy",
"postalCode": "54000",
"country": "France"
},
{
"position": 1,
"lon": 48.8566,
"lat": 2.3522,
"locality": "Paris",
"postalCode": "75000",
"country": "France"
}
]
}
```
Recurrent passenger ad :
```json
{
2023-06-27 12:14:14 +00:00
"userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
"passenger": true,
2023-10-16 15:11:20 +00:00
"seatsRequested": 1,
"frequency": "RECURRRENT",
"fromDate": "2023-01-15",
"toDate": "2023-12-31",
2023-07-26 15:05:16 +00:00
"schedule": [
{
"day": 1,
2023-10-16 15:11:20 +00:00
"time": "07:00",
2023-10-16 15:25:17 +00:00
"margin": 600
2023-07-26 15:05:16 +00:00
},
{
"day": 2,
2023-10-16 15:11:20 +00:00
"time": "07:05",
2023-10-16 15:25:17 +00:00
"margin": 600
2023-07-26 15:05:16 +00:00
},
{
"day": 5,
2023-10-16 15:11:20 +00:00
"time": "07:10",
2023-10-16 15:25:17 +00:00
"margin": 600
2023-07-26 15:05:16 +00:00
}
],
2023-06-23 13:35:37 +00:00
"waypoints": [
2023-06-02 14:31:35 +00:00
{
"position": 0,
2023-06-23 13:35:37 +00:00
"lon": 48.689445,
"lat": 6.17651,
2023-06-02 14:31:35 +00:00
"houseNumber": "5",
"street": "Avenue Foch",
"locality": "Nancy",
"postalCode": "54000",
"country": "France"
},
{
"position": 1,
2023-06-02 14:31:35 +00:00
"lon": 48.8566,
"lat": 2.3522,
"locality": "Paris",
"postalCode": "75000",
"country": "France"
}
]
}
```
The list of possible options when creating an ad :
2023-06-23 13:35:37 +00:00
- userId: the user id (as a uuid)
2023-10-16 15:11:20 +00:00
- driver (boolean): if the ad is a driver ad. Note that at least a role must be set to true (driver and/or passenger).
- passenger (boolean): if the ad is a passenger ad. Note that at least a role must be set to true (driver and/or passenger).
- frequency: `PUNCTUAL` or `RECURRENT`
2023-06-23 13:35:37 +00:00
- fromDate: start date for recurrent ad, carpool date for punctual ad
- toDate: end date for recurrent ad, same as fromDate for punctual ad
2023-10-16 15:11:20 +00:00
- schedule: an array of schedule items, a schedule item containing :
- the week day as a number, from 0 (sunday) to 6 (saturday)
2023-07-26 15:05:16 +00:00
- the departure time (as HH:MM)
2023-10-16 15:11:20 +00:00
- the margin around the departure time in seconds
- seatsProposed: number of seats proposed as driver (required if `driver` is true)
- seatsRequested: number of seats requested as passenger (required if `passenger` is true)
- strict (boolean): if set to true, allow matching only with similar frequency ads
2023-06-27 12:14:14 +00:00
- 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
2023-06-02 14:31:35 +00:00
## Messages
As mentionned earlier, RabbitMQ messages are sent after these events :
2023-06-06 08:22:50 +00:00
- **Create** (message : the created ad informations)
2023-06-02 14:31:35 +00:00
## 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
2023-06-06 08:22:50 +00:00
Mobicoop V3 - Ad Service is [AGPL licensed](LICENSE).